不要写那么多注释！

如果用很多注释来“装饰”代码是件好事的话，那么在代码中加入大片大片的注释便是锦上添花了。是这样吗？事实上不完全是这样的。过犹不及，好心也会办坏事。

'*************************************************
' Name: CopyString
'
' Purpose: This routine copies a string from the source
' string (source) to the target string (target).
'
' Algorithm: It gets the length of "source" and then copies each
' character, one at a time, into "target". It uses
' the loop index as an array index into both "source"
' and "target" and increments the loop/array index
' after each character is copied.
'
' Inputs: input The string to be copied
'
' Outputs: output The string to receive the copy of "input"
'
' Interface Assumptions: None
'
' Modification History: None
'
' Author: Dwight K. Coder
' Date Created: 10/1/04
' Phone: (555) 222-2255
' SSN: 111-22-3333
' Eye Color: Green
' Maiden Name: None
' Blood Type: AB-
' Mother's Maiden Name: None
' Favorite Car: Pontiac Aztek
' Personalized License Plate: "Tek-ie"
'*************************************************

我常常不看开发者写的注释。似乎他们并不明白，其实他们的代码已经告诉了我它是怎样工作的；我们需要注释告诉我们的是，程序为什么这样工作。代码注释已被广泛地误解和滥用，以致于你都开始怀疑它们原本的价值——注释还有存在的必要吗？你在期望什么呢？要当心！这里有一段完全没有任何注释的代码:

r = n / 2;
while ( abs( r - (n/r) ) > t ) {
  r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );

明白这段代码想要做什么吗？它看起来一清二楚，但到底是干什么用的呢？

让我们加上一行注释：

 // 用“牛顿-拉夫逊”近似法求解n的平方根
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
  r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );

这个应该就是我想要的了。不是吗？它介于完全没有任何注释与每隔一行就规规矩矩写上史诗般的注释这两种极端之间，看似一个不错的折中——你满意了吗？

未必！与其添加注释，我更愿意把这段代码重构成这样：

private double SquareRootApproximation(n) {
  r = n / 2;
  while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) );
  }
  return r;
}
System.out.println( "r = " + SquareRootApproximation(r) );

我一行注释也没有加，但这段神秘的代码现在已经非常容易理解了。 

尽管注释本身说不上好或者坏，它们却常常被用作支撑代码的“拐杖”。你应该总是专注于编写代码，而忘了还有注释这种东西的存在。这会迫使你竭尽全力使用最简单、最直白、最能自我说明的方式把代码写出来。

为了让你的程序员同伴们更易于阅读和理解你的代码，如果你已经重写、重构、甚至重新设计了很多遍——当你已经一筹莫展，已经想不出任何办法可以让你的代码变得更加浅显易懂——这时候，也只有在这时候，你才应该迫不得已地加上些注释来解释你的代码是做什么的。

就像Steve Yegge指出的那样，这是初级开发者与高级开发者之间的一个关键差别：

坦率地说，要是在以前，让我一下子看太多的代码会让我崩溃，它的复杂度已经超越了我能接受的极限。而当我不得不在那些代码的基础上继续工作的时候，我通常会把它们重写，或者至少也会写上大量的注释。现如今，当我碰到这种情况的时候我会披荆斩棘快速通过，而不会（过多地）抱怨。当我在脑子里有了一个明确的目标、并且有一段复杂的代码要写时，我会把时间花在代码实现上面，而不是（用注释）写下它的故事、讲给我自己听。

初级开发者依靠注释来讲故事，而实际上他们应该依靠代码本身。注释是“旁白”，它们有其自身的价值，但绝不能用来替代（故事里的）情节、人物和场景。

或许这才是关于代码注释不可告人的小秘密：想要写出好的注释，你必须是一位优秀的作家。注释跟代码不一样，它不是给编译器看的。注释是用来和其他人类交流想法的文字。尽管我跟（大多数）程序员同伴们关系很好，但我必须承认，与其他人有效沟通真的不是我们的强项。我曾经收到过我们小组里的一位程序员发来的电子邮件，里面只有三段，但着实把我搞得晕头转向。我们能相信这样的人会在代码里写出清晰、易懂的注释吗？于是我想，或许我们中的一些人去做那些我们擅长的事情会更好些——那就是，为编译器写代码，并且尽可能写得清楚些，而只把注释当作是最后没有办法的办法。

写出好的、有意义的注释是很难的。就像写代码一样，它是一门艺术；或许还要更加艺术一点！就像Sammy Larbi在“Common Excuses Used To Comment Code and What To Do About Them”（注释代码的常见借口以及应对方法）一文中所说的那样，如果你觉得你的代码在没有注释的情况下显得过于复杂、很难被人理解，那只能说明你的代码写得很糟糕。重写你的代码吧，直到它不再需要任何注释。如果经过了这些努力，你仍然觉得注释是必需的，那么就尽你所能加上注释吧。切记，小心！

更多 1

• 上一篇：学海无涯苦作舟
• 下一篇：结对编程与代码评审

顶

6

踩

0

查看评论

11楼  西瓜一片 1小时前发表 [回复]

注释用来解释“所以然”。其它作用：分块标记，代码定位标记，在IDE文档里嵌入有对比的颜色--更加美观和护眼。

10楼  西瓜一片 2小时前发表 [回复]

注释有时候真不能少，比如有人为了某个特定需求，往代码里贴了块狗皮膏药，就那么一段，如果没有注释，看的人可能就晕了，会为了一个次要的分支浪费很多时间。如果有一句友好的提示，说明何时何地为了什么临时目的而加，那后来人就能跳过这一段，紧扣逻辑主线。

9楼  popopening 2小时前发表 [回复]

人家母语是英语，咱们是中文，没有中文注释我会愿意把你代码都看了才怪

8楼  initphp 2小时前发表 [回复]

扯蛋的文章
show me your code！

7楼  lymastee 2小时前发表 [回复]

零散的注释确实没用。要写就来一整段，如果不能把情况完全说明清楚，就一个字不写
尽管被人骂过很多次，我还是不喜欢写注释。我很多代码经常一个字注释都没有。
rtfc。
如果一个人连静下心来读代码都做不到的话，就不要来玷污程序员这个职业了。滚蛋吧。

6楼  独行天下 2013-11-26 08:34发表 [回复]

有时候业务逻辑比较复杂，还是要有必要的注释吧，有时候不仅仅是给自己看，更多的是给后人看。

Re:  happydeer 2013-11-26 08:39发表 [回复]

回复supersugar3126：我同意。作者的意思也是说“尽量避免”写注释，而不是一概不写。也就是说，能用代码清晰表达的地方就不要写注释。思考一下，这块代码能写得更好吗？更容易让人理解，让它自说明。

5楼  retacn_yue 2013-11-25 22:48发表 [回复]

业务处理复杂的话，我会先注释后编码，不知道这是不是个坏习惯

Re:  yuloo911 2小时前发表 [回复]

回复retacn_yue：先注释后编码，其实就是先写伪代码，再细化成可用代码，很正常的方式啊。

Re:  happydeer 2013-11-25 23:00发表 [回复]

回复retacn_yue：那说明你的代码还不够好，不够“自己说明自己”。

Re:  retacn_yue 2013-11-25 23:30发表 [回复]

回复happydeer：也许

4楼  mm9696911 2013-03-28 08:17发表 [回复]

这样起名字 还不如代码注释呢

3楼  Daisy__Ben 2013-03-18 10:52发表 [回复]

可不可以在函数之前注释下这个函数的的功能是干啥的？看到有些函数之前的注释就为了解释其中一部分的变量和操作让我很烦躁，虽然那些难以理解的部分确实有解释的需要——就好像作者确实想让人仔细读他内部实现的代码一样。

Re:  happydeer 2013-03-18 13:20发表 [回复]

回复Daisy__Ben：文中的代码例子说明了，想要说明“函数的的功能是干啥的”最好的办法是给函数取一个好名字。

2楼  三断笛 2013-03-16 21:41发表 [回复]

同意1楼。

1楼  自动控制原理 2013-03-16 10:52发表 [回复]

完全不用注释的话给这些函数和变量命名要花很大的心思啊，其实完全不用注释的话有点绝对啦

Re:  happydeer 2013-03-16 21:04发表 [回复]

回复ajzcr：让中国程序员给变量、函数、类取恰当的英文名是比较困难的。。。另外，作者也并不是说绝对不要注释，他是建议我们“尽量”不要写注释，而把代码写得好一点。