4、注释

避免注释
注释并不“纯然地好”，实际上，注释最多也就是一种必须的恶。注释的恰当用法是弥补我们在用代码表达意图时的失败。如果你发现自己需要写注释，再想想看是否有办法翻盘，用代码来表达。
为什么
不准确的注释要比没注释坏得多。
注释存在的时间越久，就离其所描述的代码越远，越来越变得全然错误。原因很简单。程序员不能坚持维护注释。代码在变动，在演化。从这里移到那里。彼此分离、重造又合到一处。很不幸，注释并不总是随之变动。我们应该多花心思尽量减少注释量，真实只在一处地方有：代码。

糟糕的代码
别给糟糕的代码加注释——重新写吧：与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。

好注释
法律信息：版权说明、版本号、生成日期、作者、
提供基本信息的注释
提供了某个动作后面的意图。
阐释
警示
TODO注释 解释为什么该函数的实现部分无所作为
公共API，就该为它编写良好的Javadoc

坏注释
坏注释都是糟糕的代码的支撑或借口
喃喃自语：如果写注释，就要花必要的时间确保写出最好的注释。任何迫使读者查看其他模块的注释，都没能与读者沟通好，不值所费。
多余注释：不能比代码本身提供更多的信息。没有证明代码的意义，也没有给出代码的意图或逻辑。读它并不比读代码更容易。
误导性、不精确的注释
循规蹈矩式注释：每个函数都要有 Javadoc 或每个变量都要有注释的规矩是愚蠢可笑的。
日志型注释：每次编辑代码时，记录每次修改的注释。现在有源代码控制系统可用，这种冗长的记录只会让模块变得凌乱不堪，应当全部删除。
废话注释：对于显然之事喋喋不休，毫无新意。用整理代码的决心替代创造废话。
标记位置：尽量少用标记栏，只在特别有价值的时候用。更应该做的是缩短函数。
归属于署名：源代码控制系统非常善于记住是谁在何时添加了什么。
注释掉的代码：源代码控制系统可以记下代码，无需再用注释来标记，删掉即可。
非本地注释：如果要写注释，请确保它描述了离它最近的代码。
信息过多：别在注释中添加有趣的历史性话题或者无关的细节描述。
注释代码联系不明显：注释及其描述的代码之间的联系应该显而易见。注释的作用是解释未能自行解释的代码。如果注释本身还需要解释，就太遗憾了。
非公共代码中的Javadoc