注释规范

注释的作用是弥补我们在用代码表达意图时遭遇的失败，如果你发现自己需要写注释，说明你的代码的表达能力不够，这个时候应该想下能否使用更好的代码来表达。

代码在变动，但是注释不总是随之变动，随着时间的流逝，注释常常用其所描述的代码分隔开来，越来越不准确，与其把精力放在维护注释上还不如把力气用在写清楚代码。

不准确的注释不如没注释，只有代码能忠实地告诉你它做的事，所以，尽管有时候也需要注释，我们也应该多花心思尽量减少注释量。

有些注释是必须的，也是有利的，例如：

• 对一些难以理解的代码的注释。
• 警告其它程序员会出现某种后果的注释。
• TODO注释，TODO是一种程序员认为应该做，但由于某种原因目前还没做的工作。
• 法律信息，例如版权及著作权声明就是有理由在每个源文件开头注释处放置的内容。
• 描述接口的注释，例如Javadoc。

还有些坏注释通常是对糟糕代码的借口或错误决策的修正，例如：

• 多余的注释，注释相比代码，没能提供更多的信息，也没有证明代码的意义，也没有给出代码的意图或逻辑，读代码比读注释还要容易，这种注释就是多余的。
• 误导性注释，有些注释不够准确，常常误导其他程序员。
• 循规式注释，有些规定要求每个函数或变量都要有注释，这种规定会产生很多废话注释搞乱代码。
• 日志式注释，有些人会在每次编辑代码时，在模块开始处添加一条注释，例如2018-10-02：增加了xxx功能，我们现在已经有了源代码控制系统，没必要再写这样的注释。
• 署名注释，代码随着时间的流逝越来越和原作者没有关系，源代码控制系统是这类信息的最好归属地。
• 注释掉的代码，对于注释掉的代码，其他人会想这些代码为什么要注释掉，重要吗，它们放在那是为了给未来的修改做提示还是某人多年以前注释掉，懒得清理的过时玩意？在以前，注释的代码可能有用，但现在已经有源代码控制系统帮我们记住不要的代码，所以直接删除即可。
• HTML注释，HTML注释难以阅读，如果注释需要呈现到网页，那么应该是工具而非程序员负责给注释加上HTML标签。
• 注释应该描述离它最近的代码，别在一个函数描述远在它方的其它函数。
• 注释应该与其描述的代码之间有明显的联系，而不是让读者费解。

能用函数或变量时就别用注释，下面代码中无注释的版本比有注释的明显更好：

//xxxx注释
if (smdoule.getDependSubsytems().contains(subSysMod.getSubSystem()))

ArrayList moduleDependes=smodule.getDependSubsystems();
String ourSubSystem=subSysMod.getSubSystem();
if (moduleDependes.contains(ourSubSystem))