什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱一个模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。

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形式在源代码中放置要做的工作列表。

4.3.7 放大

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

4.3.8 公共API中的Javadoc

如果你在编写公共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 可怕的废话

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

4.4.9 位置标记

尽量少用标记栏，只在特别有价值的时候用。

4.4.10 括号后面的注释

如果你发现自己想标记右括号，其实应该做的事缩短函数。

4.4.11 归属与署名

源代码控制系统是这类信息最好的归属地。

4.4.12 注释掉的代码

直接把代码注释掉是讨厌的做法。

4.4.13 HTML注释

如果注释将由某种工具抽取出来，呈现到网页，那么该是工具而非程序员来负责给注释加上合适的HTML标签。

4.4.14 非本地信息

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

4.4.15 信息过多

别在注释中添加有趣的历史性话题或者无关的细节描述。

4.4.16 不明显的联系

注释及其描述的代码之间的联系应该显而易见。

4.4.17 函数头

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

4.4.18 非公共代码中的Javadoc

对Javadoc注释额外的形式要求几乎等同于八股文。