避免在代码里写注释

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

'*************************************************
' 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: [phone]
' 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 ToComment Code and What To Do About Them”（注释代码的常见借口以及应对方法）一文中所说的那样，如果你觉得你的代码在没有注释的情况下显得过于复杂、很难被人理解，那只能说明你的代码写得很糟糕。重写你的代码吧，直到它不再需要任何注释。如果经过了这些努力，你仍然觉得注释是必需的，那么就尽你所能加上注释吧。切记，小心！