（点击
上方公众号
，可快速关注）
编译：伯乐在线/黄小非
如有好文章投稿，请点击 → 这里了解详情
【导读】：代码注释的作用，不需要对程序员解释了。有时在查看他人代码，能看到一些令人不禁大笑的注释。比如：
或者：
// 写这段代码的时候，只有上帝和我知道它是干嘛的
// 现在只有上帝知道
最近在 Quora 上看到一个帖子，号召程序员分享自己见过最有趣的代码注释。看到了各种有趣的注释，打算分多篇摘编分享给大家。
1. Bill Poucher 的分享（他是一位计算机科学教授）
我见过的最佳注释是以 HTML 格式写在源代码里的，任何想要阅读的人都能看得见。我管它叫“Cerny效应”。
曾经有一位很有天赋的捷克研究生 Tomas Cerny，在 Baylor 大学 ICPC（国际大学生程序设计竞赛）技术研发部主任 Jeff Donahoo 博士的领导下，负责将另外一位很聪明的研究生的设计原型转换成实际产品。
有一天，Jeff 到我的办公室跟我说，在他们ICPC实验室，冷战的格局正在形成。因为有人在源代码的注释里写了一些话，冒犯到了其他人。（为了看看情况，）我就随他一起去找了Tomas。
Jeff去了以后就开门见山地问：“Tomas，你是不是在Joel的代码上加了注释，说他的代码是愚蠢（retarded）的？”Tomas倒是很坦白地说：“是的。”Jeff又问：“你凭什么这么写呢？”Tomas回答说：“因为（他的代码）确实愚蠢（retarded）啊！”
我就站在一边看着，Tomas一脸懵逼，Jeff强压怒火，场面真是大写的尴尬。接着，Tomas拿出了他的《捷克语-英语词典》，打开，上面写着，词义：“开发中（under developed）：retarded”（译注：其实retarded这个词有两个意思，既有“弱智，愚蠢”的意思，也有项目未完成，正在开发中的意思，这也是造成这个误会的原因。）
是的，开发确实还没完成……后来，Tomas就把注释修改为了“建设中（Under construction）”。然后我和Jeff都对Tomas拓展英语能力的热情捧腹大笑。我至今不知道当年这个误会是不是真的解决了。
跟你们说，我和Jeff都很爱讲这个段子，后来每当我们把Tomas介绍给ICPC新成员的时候，就一定会讲这个段子。Tomas现在已经是布拉格捷克技术大学的计算机科学系教授了，他还是学校ICPC技术部的奠基人，也是我非常好的朋友。
Tomas不仅在Baylor大学获得了硕士学位，而且他在这里找到了他的伴侣，一位音乐家，同时也是奥运会级别的田径选手。当然，这是另外一个关于奥林匹克的爱情故事了。
ICPI-ACM国际大学生程序设计竞赛，由IBM赞助。
2. Anirudha Bose 的分享：
谢尔盖.布林（Google的联合创始人之一）在斯坦福大学念计算机科学博士学位的时候，他的简历里并不含任何”待遇要求“（Objective）的字眼。但当你去查看他的简历的HTML源代码的时候，你会看到（他在简历HTML源文件里明确写了“待遇要求”，只是用注释注掉了，在浏览器页面上不显示。）：
（其“待遇要求“的内容是：办公室要大，挣钱要多，干活要少。如果能经常去奇妙的地方旅行而且还能给报销的话，那就更好了。）
3. Abhinav Upadhyay 的分享
/* You are not expected to understand this */
/* 我们并不指望你能看懂这段话 */
这段注释并不是我亲眼所见，但是它在网上传得很厉害。这段注释是出自于贝尔实验室的Unix系统第六发行版，并在《Lions’ Commentary on UNIX 6th Edition, with Source Code》这本书中标注出来的。
代码和标注的细节如下：
/*
* 切换到新进程栈，并设置其段寄存器
*/
retu
(
rp
->
p_addr
);
sureg
();
/*
* 如果新进程因为被换出而暂停，则设置其栈级别为last call，并传至sayu(u_ssay).
* 这样做的目的是确保aretu方法被调用后立即返回的值实质上是上一次调用sayu的方法的返回值。
*
* You are not expected to understand this.
* 我们并不指望你能看懂这段话
*/
if
(
rp
->
p_flag
&
SSWAP
)
{
rp
->
p_flag
=& ~
SSWAP
;
aretu
(
u
.
u_ssav
);
}
/*
* The value returned here has many subtle implications.
* See the newproc comments.
*/
return
(
1
);
4. Kalpesh Singh 的分享：
我有个坏习惯，每当我看到做得不错的网站，我就回去控制台看它的源代码。我想很多前端工程师都喜欢这么干吧。
我订购了Box8服务，并在他们的console里看到了如下信息。（伙计们，他们居然在console/源代码里面打招聘广告。我对广告什么的早就受够了，你们就不能搞点儿新花样？）
你们可以看看Box8.in的console。
不过这样真的是挺有趣的。
还有一个比较有意思的注释是target.com编程游戏网站的源代码
可查看：Code With Target via The Geekiest Contact Form (BETA)
好好享受乐趣吧！
5. Liu Wei 的分享[译注：这明显是一位来自中国的工程师]：
我在一周前在社交网站上看到很多人在讨论这个网站，网站的源代码包含了这些注释。
有人说，这家公司应该加强对代码的审核机制。有人则怀疑这家公司可能没有足够的人力资源来做代码审核，因为至少需要两个程序员才能完成这项工作。
6. Edwin Romero 的分享：
我不确认有多少人熟悉站点内的Robots.txt这个文件。其实这个文件不是运行必要的代码，但是它声明了爬虫/搜索引擎能爬到/搜到站点的哪些内容。
我在Nike网站上发现的Robots.txt文件非常有意思，如下：
如果你读一下文件头部的内容，你就会发现它是这么写的：
“…just crawl it.”
这种写法和Nike品牌著名的广告标语“Just Do It”不谋而合。
**更新**
Nike最近修改了他们的robots文件，并在里面加入了一个有趣的图案：
感谢Chris Shepherd 告诉我这个消息!
7. Soham Bhowmik 的分享：
好吧，这个回答其实并不完全是关于注释，而是关于代码。
我的第一个项目，一个为印度非常流行的新闻频道做的iOS应用，要求在交付之前制定规则。这件事情已经过去很久了，大约6年左右。当时iOS的最新版本还只是3.2。无论公司什么时候把应用交付给客户，应用都会被设置在5天之后过期，然后用户就不得不回头来找我们解决应用的问题。
代码是用Objective-C写的：
BOOL
appExpired
=
........
some
code
....;
if
(
appExpired
)
{
[
NSString
hahahahhaha
];
//will purposely crash now, will not use exit(1)
//这里故意让程序崩溃，而不使用exit(1)
}
当然，如果现在还这么写代码编译器就会报错，但是当时编译器只会给出警告信息，然后程序在运行的时候会因为调用未定义的方法而崩溃。
8. Ray Mullins 的分享
：
曾经用过IBM的VSAM系统（包括z/OS和z/VSE以及其后续版本）的人，都应该体验过这个系统的逗比特性。
我曾经在一家德国的软件公司任职，负责对一个事务处理监测程序进行技术运维和研发，这个监测程序是美国开发的，有一个针对VSAM文件的接口，那么当然程序就需要一个控制模块负责对文件进行存取操作。明显写这个控制模块的人那天过得不太如意，因为在控制模块获取通用错误方法地址的那段代码里，写着这样的注释：”VSAM又SB了（FUCKED UP AGAIN）, 到这里来。“ 更有趣的是，这些控制模块的代码被正式印到操作手册上(包括带有FUCK的那段文字)，所以在差不多20年的实践里，这个注释就这么被写在那里然后发给客户。然后直到某一天有个客户想对控制模块进行替换，然后才发现有这么个注释，然后才告诉我们。
接下来的这个不是注释，而是来自于我的实际工作。我们当时有一套内部标准和方法文档。我们的系统程序员需要为一个什么渣渣的4GL产品的延迟方法编写文档，并进行演示。他的文档草稿第一版草稿大概是这么写的：
IF
TIMEDIFF
>=
5
SAY
"THE SYSTEM IS FUCKED, PLEASE BEAR WITH US"
//如果系统 SB了，请和我们一起忍受
SLEEP
(
10
)
ENDIF
草稿写完了以后他就去忙东忙西，根本没时间搞文档，接着突然发现文档的提交期限就在晚上了。于是他就直接把草稿发给文档管理人员了，根本都没看。一周以后，上百份文档就这么被打印出来分发出去了。并且，内容就是他草稿上写的那些，一个字都没改。
9. Terry Lambert 的分享：
我最喜欢的注释有两个，都是Bill Paul写的。这家伙为FreeBSD做了大量的工作，现在受雇于Wind River System，听说这个公司最近要被Intel收购了。Bill是一个非常有才华的程序员，但是他对愚蠢的容忍度也出奇的低，并且他的幽默感也很不同寻常。
下面是我喜欢的第一条注释，这是从RelTek 8129/8139 PCI NIC 驱动程序里找到的。
/*
*
The
RealTek
8139
PCI NIC redefines the meaning
of
'low end.'
RealTek
8139
PCI
NIC
重刷了
low
逼的下限
*
这可能是史上写得最烂的
PCI
以太网控制器驱动
*
with the possible exception of the FEAST chip made by
SMC
.
*
The
8139
supports
bus
-
master
DMA
,
but it
has
a
terrible
*
interface
that nullifies any performance gains that
*
bus
-
master DMA usually
offers
.
*
*
For
transmission
,
the chip
offers
a
series of four TX
*
descriptor
registers
.
Each
transmit frame must be
in
a
*
contiguous
buffer
,
aligned
on
a
longword
(
32
-
bit
)
boundary
.
*
This
means we almost always have
to
do
mbuf copies
in
order
*
to
transmit
a
frame
,
except
in
the unlikely
case
where
a
)
*
the packet fits
into
a
single
mbuf
,
and
b
)
the packet
is
*
32
-
bit aligned within the
mbuf
's data area. The presence of
* only four descriptor registers means that we can never have
* more than four packets queued for transmission at any one
* time.
*
* Reception is not much better. The driver has to allocate a
* single large buffer area (up to 64K in size) into which the
* chip will DMA received frames. Because we don'
t
know where
*
within
this
region received packets will begin
or
end
,
we
*
have no choice but
to
copy data from the buffer area into
*
mbufs
in
order
to
pass the packets up
to
the higher
*
protocol
levels
.
*
*
It
's impossible given this rotten design to really achieve
要让这么烂的设计去达到100Mbps的速度简直就是天方夜谭
* decent performance at 100Mbps, unless you happen to have a
除非你有一台CPU强劲的电脑去驱动
* 400Mhz PII or some equally overmuscled CPU to drive it.
*
* On the bright side, the 8139 does have a built-in PHY,
* although rather than using an MDIO serial interface like
* most other NICs, the PHY registers are directly accessible
* through the 8139'
s
register
space
.
The
8139
supports
*
autonegotiation
,
as
well
as
a
64
-
bit multicast
filter
.
*
这绝对是一个很爽的注释。传说为了让 Bill 能把这段注释删掉/修订/修改/更新等等，厂家用了各种条件去诱惑他，但是他都拒绝了。
第二段注释是写在一个修改版的BSD许可证的“限制伤害”条款里的，Bill在他的代码里引用了这个许可证协议。其实它并没有对原先的协议做大的修改，所以很多人看到这个协议以后，一看跟模板差不多，然后就跳过了，几乎没什么人仔细去看整个文字。
IN
NO EVENT SHALL Bill Paul
OR
THE VOICES
IN
HIS HEAD BE LIABLE
FOR
ANY
DIRECT
,
INDIRECT
,
INCIDENTAL
,
SPECIAL
,
EXEMPLARY
,
OR
CONSEQUENTIAL
DAMAGES
怎么样，你没见过这条吧。其实很容易就看掉了。有趣的地方正好在这里：
「
Bill Paul以及他头脑中的想法绝不会直接，间接，偶然，特殊，典型或实质性地造成任何损害。
」
总之，这哥们儿是个天才。
10. Boris Zamoruev 的分享
我曾经做过一个高性能分布式键/值存储的项目。这是一个设计很精巧的软件，API非常简洁。如果你要获取一个数值，那么你就用命令：GETN(get, 数值)即可。如果你要存一个数值，那就用命令：PUTN(put, 数值)即可。其他的命令也很简单，比如MGETN(get multiple, 数值)，MPUTN(put multiple, 数值)，INCR(增量), MINCR(多个增量），（基本上命令都可以自解释）。
所有的命令都会被送到一个dispatcher函数去进行解析，辨明逻辑，然后去调用相应的处理函数。处理函数基本上也是自解释风格的，因此代码里面也不需要太多注释，例如：
int
Server
::
handle_getn
(
…
)
{
…
}
int
Server
::
handle_mgetn
(
…
)
{
…
}
不过有一天，有人让我review一下下面这段代码：
// In Soviet Russia, Putn handles you!
// 在前苏联，Putn 就会搞定你！【译注：注意，Putn 和普京的英文拼写（Putin）非常接近。普京曾经是苏联的克格勃。】
int
Server
::
handle_putn
(
…
)
