《代码整洁之道 》第四章 注释

第四章 注释

什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱一 个模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。注意，我用了“失败”一 词。我是说真的。注释总是一种失败。我们总无法找到不用注释就能表达自我的方法，所以总要有注释，这并不值得庆贺。
如果需要注释，就要想办法，能不能不要注释，使用代码去表达。注释出现太频繁，出现的时间越久，就离所描述的代码越远，因为代码一直在变动，而注释不一定跟着变动。
只有代码能忠诚的告诉我们，他做了什么事情，唯一准确的信息来源，尽管有时候我们需要添加注释，但是我们应该多花心思去减少注释。

注释并不能美化代码

写注释的原因之一就是糟糕的代码存在。
带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样得 多。与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码。

用代码来阐述

4.3 好注释

有些注释是必须的，也是有利的。

4.3.1 法律信息

有时，公司代码规范要求编写与法律有关的注释。例如，版权及著作权声明就是必须和 有理由在每个源文件开头注释处放置的内容。

4.3.2 提供信息的注释

有时，用注释来提供基本信息也有其用处，例如使用注释解释抽象方法的返回值

4.3.3 对意图的解释

有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。

4.3.4 阐释

有时，注释把某些晦涩难懂的参数或返回值的意义翻译为某种可读形式，也许是有用的。当然，更好的方法是尽量让参数或返回值足够清楚，如果参数、返回值是某个标准库或是你不能修改的，写个注释是有用的。

4.3.5 警示

用于警告其他程序员会出现某种后果的注释也是有用的。
例如，下面的注释解释了为什么要关闭某个特定的用例

4.3.6 TODO注释

TODO是一种程序员认为应该做，但由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性，或者要求他人注意某个问题。它可能是恳请别人取个好名字，或者提示对依赖于某个计划事件的修改。无论TODO的目的如何，它都不是在系统中留下糟糕的代码的借口。
大多数好IDE都提供了特别的手段来定位所有TODO注释。

4.3.7 放大

注释可以用来放大某种看来不合理之物的重要性。

4.3.8 公共API中的Javadoc

没有什么比被良好描述的公共API更有用和令人满意的了。标准Java库中的Javadoc 就是一例。没有它们，写Java程序就会变得很难。
如果你在编写公共API,就该为它编写良好的Javadoc 。不过要记住本章中的其他建议。 就像其他注释一样，Javadoc 也可能误导、不适用或者提供错误信息。

4.4 坏注释

大多数注释都属此类，通常，坏注释都是糟糕的代码的支撑或接口，或者对错误决策的修正，基本上等于程序员的自说自话。

4.4.1 喃喃自语

如果只是你觉得需要加注释或者因为过程需要加注释，那就是无畏之举，写注释也是要花时间写出好注释。

4.4.2 多余的注释

4.4.3 误导的注释

尽管初衷可嘉，但是想4-1那种代码会有误导嫌疑的注释。
有些细微的误导信息，可能会比代码本身更难阅读，也有可能会导致程序员使用错误。

4.4.4 询规式注释

如果每个函数、字段都要有javadoc或者注释这些规则是可笑的。因为很可能像4-3那样，废话的注释，还可能误导读者。

4.4.5 日志式注释

有人会在每次编辑代码时，在模块开始处加一条注释，这类注释就像是一种记录每次修改的日志，有些是类似日志的代码模块。

4.4.6 废话式注释

有些注释是废话，喋喋不休。

4.4.7 可怕的废话

4.4.8 能用函数或变量时就别用注释

4.4.9 位置标记

有时候，程序员喜欢在源代码里标记某个特别的代码。

// Actions //

这种标记就像噪音一样

4.4.10 括号后面的注释

有时，程序员会在括号后面加特殊的注释，如代码清单4-6所示，尽管这对于含有深度结构的长函数可能有意义，但只会给我们愿意写短小、封装的函数带来混乱

4.4.11 归属与署名

// Added by Rick

源代码控制系统非常善于记住是谁在何时添加了什么，写这种小签名会弄脏代码，时间久了之后，别人可能也修改了，和原作者就没有关系了。

4.4.12 注释掉的代码

直接把代码注释掉，是很讨厌的。

4.4.13 HTML注释

源代码注释中的HTML标记是一种厌物，有时候可能会因为HTML注释而变得难以阅读。
如果注释将由某种工具（例如javadoc）抽取出来，呈现到网页上，那么应该是工具而非程序员给注释加上HTML标签。

4.4.14 非本地信息

假如你一定要写注释，请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出系统级的信息。

4.4.15 信息过多
别在注释中添加有趣的历史性话题或者无关的细节描述

4.4.16 不明显的联系

注释及其描述的代码之间的联系应该显而易见。如果你不嫌麻烦要写注释，至少让读者能看着注释和代码，并且理解注释所谈何物。

4.4.17 函数头

短函数不需要太多描述。为只做一件事的短函数选个好名字，通常要比写函数头注释要好。

4.4.18 非公共代码中的javadoc

虽然Javadoc 对于公共API非常有用，但对于不打算作公共用途的代码就令人厌恶了。 为系统中的类和函数生成Javadoc 页并非总有用，而Javadoc 注释额外的形式要求几乎等同于 八股文章。