只对代码无法表达的东西写注释
本文翻译自”Comments Only What the Code Cannot Say“，来自于《程序员应该知道的97件事》一书中的某个章节。
我们知道理论与实践之间存在差异。在实践中，这个差异远大于其在理论中所描述的那样 – 一份对注释（comments）的观察数据也证实了这一点。理论上，通常的注释代码的想法听起来是值得的：它可以为读者提供更多的细节，可以解释发生了什么事情。有什么能比自我帮助更具可帮助性的呢？然而在实践中，注释却经常变成一个破坏因素。与其他书面形式一样，编写好的注释也是有技巧的。这个技巧的主要内容是知道何时不写注释。
如果代码书写得不合乎语法规范，那么编译器、解释器以及其他一些工具会提出异议。如果代码在某方面功能不正确，评审、静态分析、测试以及在产品环境下的日常使用会发现绝大多数Bug。然而对于注释呢？在《The Elements of Programming Style》一书中Kernighan和Plauger曾指出“如果注释是错误的，那么它带来的价值就是零（甚至是负值）”。可是就是这样的注释却经常以一种编码错误所不能的方式散布并存活于代码库中。它们会持续不断地分散你的注意力，提供误导信息，细微但却持续地影响着程序员的思维。
那些在技术上没错，但却没有给代码带来任何价值的注释怎么样呢？这类注释简直就是噪音。重复描述代码含义的注释没有为读者提供任何额外价值 – 先用代码表达，再用自然语言复述不能让其看起来更加真实。被注释掉的代码不是可执行代码，所以无论对读者还是对代码运行时它都无法起到任何有用的效果。它自身也会很快地变得陈旧。版本相关的注释以及被注释掉的代码试图解决有关代码版本和历史的问题。但这些问题已经被版本控制工具（更加有效地）解决了。
代码库中普遍存在的噪音类注释以及错误注释助长了程序员们忽略所有注释的行为，他们要么略过注释，要么采取积极措施将注释隐藏起来。程序员是足智多谋的，他们会绕过任何被认为可能会造成破坏的事物：将注释折叠起来；更换颜色样式，使得注释的颜色与背景色相同；编写脚本过滤掉注释。为了使代码库免遭程序员们滥用聪明才智所带来的破坏，降低因忽视真正有价值的注释所带来的风险，我们应该像看待代码那样看待注释。每条注释都应该为读者带来一些价值，否则这些注释就是无用的，应该被删除或重写。
那么，什么才是有价值的呢？注释应该表达那些代码没有表达以及无法表达的东西。如果一段注释被用于解释一些本应该由这段代码自己表达的东西，我们就应该将这段注释看成一个改变代码结构或编码惯例直至代码可以自我表达的信号。我们重命名那些糟糕的方法和类名，而不是去修补。我们选择将长函数中的一些代码段抽取出来形成一些小函数，这些小函数的名字可以表述原代码段的意图，而不是对这些代码段进行注释。尽可能的通过代码进行表达。你通过代码所能表达的和你想要表达的所有事情之间的差额将为注释提供了一个合理的候选使用场合。对那些代码无法表达的东西进行注释，而不要仅简单地注释那些代码没有表达的东西。
评论