代码整洁之道_04注释
第四章 注释
“别给糟糕的代码加注释，重写吧”——大牛
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。注释总是一种失败，我们总无法找到不用注释就能表达自我的方法，所以总要有注释，这并不值得庆贺。
每次用代码表达都该夸奖一下自己。
每次写注释，都该做个鬼脸，感受自己在表达能力上的失败！
0. 为什么贬低注释
因为注释会撒谎。
- 注释存在的时间越久，离其所描述的代码就越远：程序员不能坚持维护注释；
- 注释并不总随着代码走，而代码在变动，在演化，在复制粘贴中迷失自我。
1、好注释
- 法律信息；
- 提供信息的注释；
- 对意图的解释；
- 阐释，把某些晦涩难明的参数或返回值的意义翻译为某种可读形式；
- 警示，可能会出现某种后果的注释；
- TODO注释；
- 放大，放大某种看来不合理之物的重要性；
- 公共API中的 Javadoc；
2、坏注释
喃喃自语
多余的注释
误导性注释
循规式注释
日志式注释
废话注释
可怕的废话
能用函数或变量时就别用注释
位置标记
括号后面的注释
归属与署名
注释掉的代码
HTML注释
非本地信息，别在本地注释的上下文环境中给出系统级的信息
信息过多
不明显的联系
函数头
非公共代码中的Javadoc