注释规约
(三) 注释规约
Rule 1.【推荐】基本的注释要求
完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
代码将被大量后续维护，注释如果对阅读者有帮助，不要吝啬在注释上花费的时间。(但也综合参见规则2，3)
第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。
除了特别清晰的类，都尽量编写类级别注释，说明类的目的和使用方法。
除了特别清晰的方法，对外提供的公有方法，抽象类的方法，同样尽量清晰的描述：期待的输入，对应的输出，错误的处理和返回码，以及可能抛出的异常。
Rule 2. 【推荐】通过更清晰的代码来避免注释
在编写注释前，考虑是否可以通过更好的命名，更清晰的代码结构，更好的函数和变量的抽取，让代码不言自明，此时不需要额外的注释。
Rule 3. 【推荐】删除空注释，无意义注释
《Clean Code》建议，如果没有想说的，不要留着IDE自动生成的，空的@param，@return，@throws 标记，让代码更简洁。
反例：方法名为put，加上两个有意义的变量名elephant和fridge，已经说明了这是在干什么，不需要任何额外的注释。
/**
* put elephant into fridge.
*
* @param elephant
* @param fridge
* @return
*/
public void put(Elephant elephant, Fridge fridge);
Rule 4.【推荐】避免创建人，创建日期，及更新日志的注释
代码后续还会有多人多次维护，而创建人可能会离职，让我们相信源码版本控制系统对更新记录能做得更好。
Rule 5. 【强制】代码修改的同时，注释也要进行相应的修改。尤其是参数、返回值、异常、核心逻辑等的修改
Rule 6. 【强制】类、类的公有成员、方法的注释必须使用Javadoc规范，使用/** xxx */格式，不得使用//xxx方式
正确的JavaDoc格式可以在IDE中，查看调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
Rule 7. 【推荐】JavaDoc中不要为了HTML格式化而大量使用HTML标签和转义字符
如果为了Html版JavaDoc的显示，大量使用<p\> <pre\>这样的html标签，以及< " 这样的html转义字符，严重影响了直接阅读代码时的直观性，而直接阅读代码的几率其实比看Html版的JavaDoc大得多。
另外IDE对JavaDoc的格式化也要求<p>之类的标签来换行，可以配置让IDE不对JavaDoc的格式化。
Rule 8. 【推荐】注释不要为了英文而英文
如果没有国际化要求，中文能表达得更清晰时还是用中文。
Rule 9. 【推荐】TODO标记，清晰说明代办事项和处理人
清晰描述待修改的事项，保证过几个月后仍然能够清楚要做什么修改。
如果近期会处理的事项，写明处理人。如果远期的，写明提出人。
通过IDE和Sonar的标记扫描，经常清理此类标记，线上故障经常来源于这些标记但未处理的代码。
正例：
//TODO:calvin use xxx to replace yyy.
反例：
//TODO: refactor it
Sonar: Track uses of "TODO" tags
Sonar: Track uses of "FIXME" tags
Rule 10. 【推荐】合理处理注释掉的代码
如果后续会恢复此段代码，在目标代码上方用///说明注释动机，而不是简单的注释掉代码。
如果很大概率不再使用，则直接删除（版本管理工具保存了历史代码）。
Sonar: Sections of code should not be "commented out"