第 4 章 注释
“别给糟糕的代码加注释—重新写吧。” — Brian W,Kernighan 与 P.J.Plaugher
什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱一个模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。我们总无法找到不用注释就能表达自我的方法，所以总要有注释，这不值得庆贺。
如果你发现自己需要写注释，再想想看是否有办法翻盘，用代码来表示。
注释存在的事件越久，就离其所描述的代码越远，越来越变得全然错误。原因很简单。程序员不能坚持维护注释。
程序员应当负责将注释保持在可维护、有关联、精确的高度。但我更主张把力气用在写清楚代码上，直接保证无序编写注释。
不准确的注释要比没注释的代码坏的多。
尽管有时也需要注释，我们也该多花心思尽量减少注释量。
4.1 注释不能美化糟糕的代码
写注释的常见动机之一是糟糕的代码的存在。
带有少量注释的整洁而有表达力的代码，要比带有大量注释的零散而复杂的代码像样的多。与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码。
4.2 用代码来阐述
只要想上那么几秒钟，就能用代码解释你大部分的意图。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。
4.3 好注释
唯一真正好的注释是你想办法不去写的注释。
4.3.1 法律信息
有时，公司代码规范要求编写与法律相关的注释。例如，版权及著作权声明就是必须和有理由在每个源文件开头注释处放置的内容。
这类注释不应是合同或法典。只要有可能，就指向一份标准许可或其他外部文件，而不要把所有条款放到注释中。
4.3.2 提供信息的注释
有时，用注释来提供基本信息也有其用处。
这类注释有时管用，但更好的方式是尽量利用函数名称传达信息。
4.3.3 对意图的解释
有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。
4.3.4 阐释
有时，注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式，也会是有用的。通常，更好的方法是尽量让参数或返回值自身就足够清楚；但如果参数或返回值是某个标准库的一部分，或是你不能修改的代码，帮助阐释其含义的代码就会有用。
4.3.5 警示
有时，用于警告其他程序员会出现某种后果的注释也是有用的。
4.3.6 TODO 注释
有时，有理由用 //TODO 形式在源代码中放置要做的工作列表。
TODO 是一种程序员认为应该做，但由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性，或者要求他人注意某个问题。它可能是恳请别人取个好名字，或者提示对依赖于某个计划事件的修改。无论 TODO 的目的如何，它都不是在系统中留下糟糕的代码的借口。
如今，大多数好 IDE 都提供了特别的手段来定位所有 TODO 注释，这些注释看来丢不了。你不会愿意代码因为 TODO 的存在而变成一堆垃圾，所以要定期查看，删除不再需要的。
4.3.7 放大
注释可以用来放大某种看来不合理之物的重要性。
4.3.8 公共 API 中的 Javadoc
没有什么比被良好描述的公共 API 更有用和令人满意的了。标准 Java 库中的 Javadoc 就是一例。没有它们，写 Java 程序就会变得很难。
如果你在编写公共 API ，就该为它编写良好的 Javadoc 。
4.4 坏注释
大多数注释都属于此类。通常，坏注释都是糟糕的代码的支撑或借口，或者对错误决策的修正，基本上等于程序员自说自话。
4.4.1 喃喃自语
如果只是因为你觉得应该或者因为过程需要就添加注释，那就是无谓之举。如果你决定写注释，就要花必要的时间确保写出最好的注释。
任何迫使读者查看其它模块的注释，都没能与读者沟通好，不值所费。
4.4.2 多余的注释
多余的注释并不能比代码本身提供更多的信息。它没有证明代码的意义，也没有给出代码的意图或逻辑。读它并不比读代码更容易。事实上，它不如代码精确，误导读者接受不精确的信息，而不是正确地理解代码。
4.4.3 误导性注释
有时，尽管初衷可嘉，程序员还是会写出不够精确的注释。
4.4.4 循规式注释
所谓每个函数都要有 Javadoc 或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释徒然让代码变得散乱，满口胡言，令人迷糊不解。
4.4.5 日志式注释
有人会在每次编辑代码时，在模块开始处添加一条注释。这类注释就像是一种记录每次修改的日志。很久之前，在模块开始处创建并维护这些记录还算有道理。那时，我们还没有源代码控制系统可用。如今，这种冗长的记录只会让模块变得凌乱不堪，应当全部删除。
4.4.6 废话注释
与其纠缠于毫无价值的废话注释，程序员应该意识到，他的挫败感可以由改进代码结构而消除。
用整理代码的决心替代创造废话的冲动吧。你会发现自己成为更优秀、更快乐的程序员。
4.4.7 可怕的废话
Javadoc 也可能是废话。
如果作者在写（或粘贴）注释时都没花心思，怎么能指望读者从中获益呢？
4.4.8 能用函数或变量时就别用注释
如果能用函数或变量名表示清楚代码的含义，就别用注释了。
4.4.9 位置标记
如果标记栏不多，就会显而易见。所以，尽量少用标记栏，只在特别有价值的时候用。如果滥用标记栏，就会沉没在背景噪音中，被忽略掉。
4.4.10 括号后面的注释
在括号后面放置特殊的注释，尽管这对于含有深度嵌套的长函数可能有意义，但只会给我们更愿意编写的短小、封装的函数带来混乱。如果你发现自己想标记右括号，其实应该做的是缩短函数。
4.4.11 归属与署名
源码控制系统非常善于记住是谁在何时添加了什么。没必要用那些小小的签名搞脏代码。
源代码控制系统是这类信息最好的归属地。
4.4.12 注释掉的代码
直接把代码注释掉是讨厌的做法。别这么干！
4.4.13 HTML 注释
源代码注释中的 HTML 标记是一种厌物。编辑器/ IDE 中的代码本来易于阅读，却因为 HTML 注释的存在而变得难以卒读。如果注释将由某种工具（例如 Javadoc ）抽取出来，呈现到网页，那么该是工具而非程序员来负责给注释加上合适的 HTML 标签。
4.4.14 非本地信息
假如你一定要写注释，请确保它描述了离它最近的代码。别再本地注释的上下文环境中给出系统级的信息。
4.4.15 信息过多
别在注释中添加有趣的历史性话题或者无关的细节描述。
4.4.16 不明显的联系
注释及其描述的代码之间的联系应该显而易见。如果你不嫌麻烦要写注释，至少让读者能看着注释和代码，并且理解注释所谈何物。
注释的作用是解释未能自行解释的代码。如果注释本身还需要解释，就太遗憾了。
4.4.17 函数头
短函数不需要太多描述。为只做一件事的短函数选个好名字，通常要比写函数头注释要好。
4.4.18 非公共代码中的 Javadoc
虽然 Javadoc 对于公共 API 非常有用，但对于不打算作公共用途的代码就令人厌恶了。为系统中的类和函数生成 Javadoc 页并非有用，而 Javadoc 注释额外的形式要求几乎等同于八股文章。