我见过最有趣的代码注释,都在这里了(1)

【导读】:代码注释的作用,不需要对程序员解释了。有时在查看他人代码,能看到一些令人不禁大笑的注释。比如:

或者:

最近在 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 的分享

这段注释并不是我亲眼所见,但是它在网上传得很厉害。这段注释是出自于贝尔实验室的Unix系统第六发行版,并在《Lions’ Commentary on UNIX 6th Edition, with Source Code》这本书中标注出来的。

代码和标注的细节如下:

出处

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写的:

当然,如果现在还这么写代码编译器就会报错,但是当时编译器只会给出警告信息,然后程序在运行的时候会因为调用未定义的方法而崩溃。

8. Ray Mullins 的分享:

曾经用过IBM的VSAM系统(包括z/OS和z/VSE以及其后续版本)的人,都应该体验过这个系统的逗比特性。

我曾经在一家德国的软件公司任职,负责对一个事务处理监测程序进行技术运维和研发,这个监测程序是美国开发的,有一个针对VSAM文件的接口,那么当然程序就需要一个控制模块负责对文件进行存取操作。明显写这个控制模块的人那天过得不太如意,因为在控制模块获取通用错误方法地址的那段代码里,写着这样的注释:”VSAM又SB了(FUCKED UP AGAIN), 到这里来。“ 更有趣的是,这些控制模块的代码被正式印到操作手册上(包括带有FUCK的那段文字),所以在差不多20年的实践里,这个注释就这么被写在那里然后发给客户。然后直到某一天有个客户想对控制模块进行替换,然后才发现有这么个注释,然后才告诉我们。

接下来的这个不是注释,而是来自于我的实际工作。我们当时有一套内部标准和方法文档。我们的系统程序员需要为一个什么渣渣的4GL产品的延迟方法编写文档,并进行演示。他的文档草稿第一版草稿大概是这么写的:

草稿写完了以后他就去忙东忙西,根本没时间搞文档,接着突然发现文档的提交期限就在晚上了。于是他就直接把草稿发给文档管理人员了,根本都没看。一周以后,上百份文档就这么被打印出来分发出去了。并且,内容就是他草稿上写的那些,一个字都没改。

9. Terry Lambert 的分享:

我最喜欢的注释有两个,都是Bill Paul写的。这家伙为FreeBSD做了大量的工作,现在受雇于Wind River System,听说这个公司最近要被Intel收购了。Bill是一个非常有才华的程序员,但是他对愚蠢的容忍度也出奇的低,并且他的幽默感也很不同寻常。

下面是我喜欢的第一条注释,这是从RelTek 8129/8139 PCI NIC 驱动程序里找到的。

这绝对是一个很爽的注释。传说为了让 Bill 能把这段注释删掉/修订/修改/更新等等,厂家用了各种条件去诱惑他,但是他都拒绝了。

第二段注释是写在一个修改版的BSD许可证的“限制伤害”条款里的,Bill在他的代码里引用了这个许可证协议。其实它并没有对原先的协议做大的修改,所以很多人看到这个协议以后,一看跟模板差不多,然后就跳过了,几乎没什么人仔细去看整个文字。

怎么样,你没见过这条吧。其实很容易就看掉了。有趣的地方正好在这里:

Bill Paul以及他头脑中的想法绝不会直接,间接,偶然,特殊,典型或实质性地造成任何损害。

总之,这哥们儿是个天才。

10. Boris Zamoruev 的分享

我曾经做过一个高性能分布式键/值存储的项目。这是一个设计很精巧的软件,API非常简洁。如果你要获取一个数值,那么你就用命令:GETN(get, 数值)即可。如果你要存一个数值,那就用命令:PUTN(put, 数值)即可。其他的命令也很简单,比如MGETN(get multiple, 数值),MPUTN(put multiple, 数值),INCR(增量), MINCR(多个增量),(基本上命令都可以自解释)。

所有的命令都会被送到一个dispatcher函数去进行解析,辨明逻辑,然后去调用相应的处理函数。处理函数基本上也是自解释风格的,因此代码里面也不需要太多注释,例如:

不过有一天,有人让我review一下下面这段代码:

我当即就选择了通过,然后合并到代码库并且发布了。据我所知,现在这段代码还在代码库里。

11. Nikunj Madhogaria 的分享

我最喜欢的一个注释是:

读者如果不明白什么意思,请看下图:

12. Sasha Krassovsky 的分享

曾经有一次, 我从学生交给我的代码里随便挑了一份来看,然后发现了这么一条注释:

当然,我就是要试一下如果把注释删除了到底会怎么样。所以我就删除了,然后重新编译。结果程序真的就不能运行了。然后我把注释重新加回去,结果又好了。

删掉注释以后会报错 LINK1000,根据链接器错误文档的说明,错误的原因直接就是:“未知错误;请参考文档或寻求技术支持。”

为什么这个注释不能去掉呢?我估计这个问题对我来说一直就是个谜。

13. Wojtek Swiatek 的分享

我看过一些数据分析的代码,然后就被下面的注释震惊了:

 14. Michael Dehmlow 的分享

我新入职了一个公司,然后发现了一段三周之前写的注释,这段注释是项目之前的研发团队写的,写的日期就是我来公司面试和正式入职的这段期间。

我有幸在原来负责这个项目的先生们被炒鱿鱼的前一天被派来参与这个项目。

15. Ryan Jentzsch 的分享

好多年前我在一个公司工作,我现在都还保留着那时的磁盘,上面有我当时写的程序代码和我对前任CEO留下的注释。

(本系列刚开始,还有后续,等着瞧~ )

打赏支持我写出更多好文章,谢谢!

打赏作者

打赏支持我写出更多好文章,谢谢!

4 3 收藏 3 评论

关于作者:黄小非

黄小非:毕业于重庆大学计算机系,南开大学软件工程硕士,SCJP。 目前在一家国企信息中心任职软件开发工程师。主要技术兴趣为Java平台相关技术、系统构架、C/C++、计算机图形学等。(新浪微博:@黄小非) 个人主页 · 我的文章 · 58

相关文章

可能感兴趣的话题



直接登录
最新评论
跳到底部
返回顶部