导读：开发者都认同代码是一种资产，是软件项目中最有价值的元素，值得花费时间、精力和金钱。

但是你怎么认定责任？

当你看得更深一点时，可能会对自己的发现感到惊讶。我们的软件质量可能与你的预期不太一样，你也可能会发现一些有趣的注释。

欢迎所有开发者，还有所有富有同情心的人们。

每个技术人都至少给自己的代码写过一次注释，这点是肯定的。

想想是你的代码还是别人的？这些注释真的有用吗？或者他们只是为了在下一次代码审查的队友和领导打气？

我们尝试讨论一下并找到这些问题的答案。尝试了解在程序中留下注释的人的动机。在本文中，我们专注于非标准和有意思的注释，并为大家提供一些有点酷的例子。开始～

简介

任何的研究通常都是从历史开始的，对历史研究越深，人生走得越好。我们仍来遵循这个传统。

首先，我们来检查程序与代码注释。

现在人们已经不会再争辩编程是不是艺术，它几乎和写作、绘画一样，但有一点技术和哲学。

而实际上，现代程序是一本书，其中包含编译器或带有编译器的虚拟机的说明文档。然而，这本代码“书”不仅可以被机器阅读，也应该被人类阅读。人们不仅要看，还要编辑代码，这是需要花不少时间和精力的。

因此，开发者尽管有创意元素，但是他的工作要按规则行事。所以开发者的情感成分非常重要。

人是一种社会存在，我们需要交流，而且与机器交流那是相当的困难。阅读带有解释或有趣评论的代码那是多么的欢乐！如果另一个开发人员也留下了消息，那就更好了。他们可能没想到你会读到它。

感受到情节了吗？来，交流吧。

一般情况下，你们是彼此完全陌生的人。但在这些时刻，你们几乎是在一起工作的。你在代码迷宫中徘徊，并试图弄清楚代码是如何工作的。所以请你一定留下彼此的暗示和复活节彩蛋。嗯，这也是团队合作！

另外，你经常需要发泄一下。如果这个“蒸汽”是由代码引起的，注释可以像下面这样吹嘘：

//Dear future me. Please forgive me.（亲爱的未来的我，请原谅我）
//I can't even begin to express how sorry I am.（我无法表达我有多报歉）

一点小历史

让我们回到历史（比如说是古代），当然还有写作——还有什么比这个词更古老的呢？尤其是最开始的那个。

科学家们认为，最初有洞穴壁画，这是穴居人潜意识里想要给他们的同伴或后代留下历史信息的愿望。它们捕捉生活、习俗、狩猎或假期的场景，还有对日常生活（包括艰苦）生活的一种注解。

是的，他们已经尽力了，百且他们也做到了。

然后有各种各样的事情记录流传了下来。写作的历史是颇有些迷人的，但也有点模棱两可。

不管怎么样，人类已经走了很长一段路，从美索不达米亚泥板上的绘图到现代数字文本的自动方法。当然，也包括本文要讨论的代码中如何优雅的加注释。

现在，技术飞速发展的二十世纪来了。先来看，下面是第一台机械和电子计算机，你知道，梅赛德斯也制造算术计算机。

当然，第一个程序的注释写得并不咋地。

我不确定人们是否考虑过它们。那时候的开发人员使用打孔卡进行编程，他们在这些卡片上写一些有趣的东西，比如：“嘿，伙计，看看这个图案很酷”。

但是有人会欣赏吗？

世界上第一台计算机庞大而复杂，用于非常严谨的计算，开发人员也很认真。

他们怎么能留下有意思的注释？

下图中的这位男士应该是对打印输出中的某些内容感到满意。

我们回到当代史。

如今每家每户都有电脑，编程也不再是一项特殊的工作。现在程序代码也很容易地创建、修改和添加注释。

其实，人们最重要的是利用这个机会。

没有什么比不匹配地形的地图，或者不匹配代码的注释更糟糕的事了：

/**
 * Always returns true.
*/
public boolean isAvailable() {
    return false;
}

开发人员多久写一次注释，尤其是有意思的注释？

目前没有确切的统计数据。为了满足我的兴趣，本人在代码分析器中计算了注释的百分比（占总行数）。以下是每种编程语言的统计数据：

• C++：大概 1 082 000 行，15% 的注释；

• C#：大概 509 000 行，6% 的注释；

• Java：大概 80 000 行，16% 的注释。

这里应该能得出什么结论？

这是不是意味着 C# 人员比 C++ 人员更懒，因此他们很少加代码注释？:) 还是这帮人的代码如此酷炫，可读性非常强，以至于他们不需要加任何内容的注释？

我看了一些注释，都还写得挺认真的。除了在很多地方我看到了经典的“请勿触摸！！！”或者“勿删，有用”。

我很高兴看到这些，对于开发人员来说，并没有什么是陌生的。

注释示例

好吧，开发人员的注释怎么样？有趣吗？

我们可以在网上找到很多示例。我在 Stack Overflow 上发现了一个经典但又流行的问题：“你遇到过的源代码中最好的注释是什么？ ”。

这个问题有 518 个答案，我在本文中引用了其中几个。

起初，我想在这里评价最经典的评论。我也浏览了一些低分答案，但我觉得它们也很有意思。

Stack Overflow 的一些人回复有点情绪化，甚至包含强烈的用词。在这种情况下，我会给出评论的链接，而不再粘贴文本。但是这些链接里通常包含非常有趣的东西。

诗歌

让我们从最受欢迎的答案开始，它有1460 票。

第一个叫做代码诗。应该是一个被代码耽误的诗人写的。以下是全文：

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/

这是一个经典的例子，展示了如何为没有灵魂的代码带来强大的情感成分。当然，你不应该定期收到此类消息。但我敢肯定——当遇到这样的注释时，会点燃人们积极的情绪。

交互性

来自同一答案的第二条注释增加了一点互动性，把工作变成了游戏：

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 42
//

作者说，他们其实没有发布带有此计数器的代码。但即使它也是为自己制作的，这也是鼓励交流注释中的一个好例子。

代码魔术

“我不知道如何写出来的，但它有效”。

我觉得每个开发者在自己的代码中至少留下一次这样的东西。下面是经典代码例子之一：

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

在其它答案中，也可以找到类似注释：

// Magic. Do not touch.

还有一个：

// I put on my robe and wizard hat...

顺便说一句，我从某个地方复制了我的祖传“魔法”代码，但我始终没弄明白它是如何工作的。:)

未知

开发人员经常高估其代码的复杂性。结果我们会得到以下注释：

/* You are not meant to understand this */

或许作者其实什么都不懂：

/**
 * If you don't understand this code, you should be flipping
 * burgers instead.
*/

有时候，我们需要先看一下代码，然后再看注释。

//Abandon all hope ye who enter beyond this point

你不敢动它！

答案里一些注释，警告不要对代码编辑或提供此操作的负面后果。比如：

// Autogenerated, do not edit. All changes will be undone.

这条注释写得有点精致，不能留在普通代码中，你不这样觉得吗？

这里有一个更详细的解释，告诉你为什么应该决定不修改：

/*
 * You may think you know what the following code does.
 * But you dont. Trust me.
 * Fiddle with it, and youll spend many a sleepless
 * night cursing the moment you thought youd be clever
 * enough to "optimize" the code below.
 * Now close this file and go play with something else.
 */

下面是另一条禁止删除注释的注释：

// If this comment is removed the program will blow up

另一个更明确的警告：

// I know the line below is wrong, but it came that way from our IP
// vendor, and the driver won't work if you "fix" it. I've had to
// revert this change 4 times now. Leave it alone, or 
// I will hunt you down and hurt you

这个代码块中的最后一段：

// (c) 2000 Applied Magic, Inc.
// Unauthorized use punishable by torture, mutilation, and
// vivisection.

这段注释告诉你，如果程序没坏，还能跑，就不要去手欠去修改它。

数字与孤单

在本文的开头，我们写了关于开发人员之间缺乏沟通，还有一些情感有点孤单的文章。以下是一些证据：

// sometimes I believe compiler ignores all my comments

还有一个：

//Mr. Compiler, please do not read this.

这是一个要求，但是他对谁说的？

/* Please work */

对吗？程序员就是这样——富有创造力，还具有很强的自黑式幽默。但是，有时他们也会感到孤单，我们看似乎多次尝试与机器交流。

暴脾气的注释

是的，代沟不是开玩笑的。这里有一个老程序员的抱怨：

* ...and don't just declare it volatile and think you've solved
* the problem. You young punks think you know what volatile
* means... why in my day we had to cast it volatile uphill
* both ways, and the code still didn't work! Whippersnappers...

是的，过几天一切都好起来了。

明天再干

拖延是我们这个时代的顽疾。当然开发人员也无法避免这种情况。下面代码中就有一个特殊 TODO 注释示例：

// drunk, fix later

我倒不太支持这种行为，但毕竟我们都是人类。下面是另一个 TODO注释，但这里好像出了点问题：

// TODO: Fix this.  Fix what?

如果不清楚在注释中写什么，可以这样用：

// TODO make this work

如果不想写长评论：

// THE LOOP THAT DO EVERYTHING!!!!!!!

如果现在没有时间写注释，这里来个友情提示：

-- Comment this later

我先去睡一觉，然后再来补上。

讲清楚

我们怎么能错过明显先生式的注释呢？这是一个栗子：

return 1; # returns 1

另一个：

i++; // increment variable i

是的，如果没有解释，显然不可能理解这里的任何事情。谢谢你，老先生。

一些有趣的代码

我遇到了几个有趣的结构示例——编程语言的关键字、变量名和注释的组合。看起来真的很有趣。这是这样的评论之一：

long john; // silver

另一个例子：

long long ago; /* in a galaxy far far away */

这是个有趣的注释：

double penetration; // ouch

从注释来看，作者也认为自己在构造模棱两可的东西。

另一个有点辣眼睛的注释：

virgin = 0;     /* you're not a virgin anymore, sweety */

好吧，用减号会更难看。

注释无罪！

这些注释背后都有一个故事。例如，这是经典免责声明的一个版本：

// I am not responsible of this code.
// They made me write it, against my will.

另一个免责声明（以及另一个开发者的复活节彩蛋）：

/*
This isn't the right way to deal with this, but today is my last
day, Ron just spilled coffee on my desk, and I'm hungry, so this
will have to do...
*/

return 12; // 12 is my lucky number

我喜欢42，它是我的幸运数。还有一个部分承认有罪过的注释：

// If this code works, it was written by Paul DiLascia. If not,
// I don't know who wrote it

你是个狡猾的人，Paul。正如我一直说的，编程是一项艰苦的工作。

// This is crap code but it's 3 a.m. and I need to get this working.

不过，没有人会在晚上分散你的注意力。

咖啡时间

来烹饪点幽默怎么样？

} catch (PartInitException pie) {
    // Mmm... pie

当然，还有咖啡：

// need a coffee to fix this.

芹菜为什么会枯萎？点击链接获取答案：

// Wilted celery?

这是我们开发者追求健康的生活方式。

不是我的

评论别人的代码？So easy！我遇到了一些无害的示例：

// This only exists because Scott doesn't know how to use const
// correctly

到最情绪化的时候了。有趣的是——代码和注释并不是由作者发布的。他们无意中在 Stack Overflow 上找到了这个答案，并决定给出注释。

开发人员也会对自己的代码进行情感注释。特别是如果它是 Quake III ，会有一些硬核型编码。

不光光文字

有时候，光是文字表现力也是不够的，可以用好的伪图形来拯救并展示整个范围的感受。

我们也是不能忽略它，就像这样：

## Safety pig has arrived!
##                               _
##  _._ _..._ .-',     _.._(`))
## '-. `     '  /-._.-'    ',/
##    )         \            '.
##   / _    _    |             \
##  |  a    a    /              |
##  \   .-.                     ;  
##   '-('' ).-'       ,'       ;
##      '-;           |      .'
##         \           \    /
##         | 7  .__  _.-\   \
##         | |  |  ``/  /`  /
##        /,_|  |   /,_/   /
##           /,_/      '`-'
##

后面的人们会对此源代码感到惊奇或夸赞。

价值超过一千字

当开发人员留下简短注释时，这也是很酷。但在这里他们做得貌似有些过头：

// HERE

发表完注释后，本工该睡觉了：

// zzzzZZZZzzzz....

也许是个实践哲学：

# let's pretend we are free, for a while

节省编码精力的诀窍来源于此。

可怕的注释

我发现了一条带有一点神秘主义的注释：

// This will save us ~0.5 sec for every user and please the machine spirits.

百感交集：有点点可怕，但也挺有趣：

// Choose! Choose the form of the Destructor!
// The choice is made! The Traveler has come!

无论如何，只要不是召唤反汇编程序就行。

其它非主流

一些不属于任何类别的评论。程序员的发布历史。封闭私人版：

//3.4  JeK  My manager promised me a lap dance if I can fix this
//          release
//3.5  JeK  Still waiting for that dance from my manager
//3.6  JeK  My manager got changed, the new manager is hairy, dont
//          want the dance anymore
//3.7  Jek  Got that dance, yuck!

通常，注释与代码是不分家的。可能也有些例外：

// This comment is self explanatory.

这个注释适用于所有场合。这里需要有人完成相应的注释。适合领导人下达的明确表示法：

//Please comment on your source code

当你的一生只是注释。法律支持永远你，不会受到任何伤害：

/* My lawyer told me not to reveal */

小结

最后，我向大家展示两条富力含所有编程智慧与哲学的注释。

第一条：

'NO COMMENT

第二条：

// nobody read comments!

就是这样。

我认为比较明显的代码注释是无限的。我们还可以找到一百万个有趣和无趣的例子。注释你的代码，评论别人的，让它变得有趣一些。

当然，记得在发布当天更正注释中的语法Bug！

祝你好运！

// good luck!

作者：万能的大雄