17. 只对代码说明不了的作注释

只对代码说明不了的作注释

        理论和实践的区别，在实践中比理论上更大——这肯定对注释也适用。理论上，一般认为代码注释是值得的：给读者提供细节，解释在做什么。还有什么比有帮助更有帮助呢？实践中，注释却经常变得不好。和其它形式的写作一样，编写好的注释也是有技巧的，大多数技巧在于知道什么时候不用写注释。
        如果代码组织有问题，编译器、解释器和其它工具肯定会提示出来。如果代码某些地方功能不正确，审查、静态分析、测试以及产品环境中的日常使用会发现大部分bug。但是注释呢？在编程风格要素（The Elements of Programming Style）一书中，kernighan和Plauger写到“如果注释是错的，那它的价值就是0（或者负值）。”然而这样的注释经常随处存留在代码库中，代码错误不不会这样。它们经常是分心和误导的源泉，对程序员的思维产生不自觉却不断的拖累。
        技术上没有错误，但是加上了对代码也没有什么价值的注释怎么样呢？只会是噪音。只在重复代码意思的注释对读者没有提供任何额外信息——用代码表达了再用自然语句表达一遍，不会让它更加真实。被注释了的代码是不会执行的，所以它对读者或者是运行时都没有帮助，很快就变得陈腐了。版本相关的注释和被注释的代码尝试阐明版本和历史中的问题，这些问题已经（更有效地）由版本控制工具说明了。
        代码库中流行着嘈杂的和不正确的注释，会促使程序员们忽略所有的注释，或者是跳过它们，或者是采用某些方法隐藏它们。程序员们都很机灵，会绕过任何会察觉到不好的东西：把注释折叠起来；更改主题颜色以使注释与背景同色；用脚本把注释筛选出。为了避免代码库中程序员的聪明才智被这样错误地应用，同时减少忽视任何纯正的注释的风险，注释应该像代码一样对待。每个注释应该给读者创建价值，否则它只是一种浪费，应该被移除或者重写。
        怎么衡量价值呢？注释应该说明一些代码没有说明或者不能说明的东西。注释在解释本应该由代码来说明的东西，这预示着该修改代码结构或习惯以使其能自我表达。与其补充说明方法或者类的糟糕名字，不如给它们重命名。与注释说明长函数中的代码块，不如从中提取出名称能表达代码块意图的小函数。尝试通过代码表达尽可能多的信息。任何你可以用代码表达的和你想整体表达的东西之间的不足，就是可以是一个合理的注释。注释代码不能表达的，而不是简单地注释代码没有表达的。

原文：Comment Only What the Code Cannot Say by Kevlin Henney