代码整洁之道02
注释总是一种失败。
代码在演化，注释却不总是随之变动。
不准确的注释比没注释坏的多。
1.用代码来阐述 创建一个与注释所言同一事物的函数即可
// check to see if the employee is eligible for full benefits if ((employee.falgs & HOURLY_FLAG) && (employee.age > 65)) 应替换为
if (employee.isEligibleForFullBenefits()) 2.好注释 法律信息
提供基本信息，如解释某个抽象方法的返回值
对意图的解释，反应了作者某个决定后面的意图
阐释。把某些晦涩的参数或者返回值的意义翻译成可读的形式(更好的方法是让它们自身变得足够清晰，但是类似标准库的代码我们无法修改):
if (b.compareTo(a) == 1) //b > a 警示。 // don't run unless you have some time to kill
TODO注释
放大 一些看似不合理之物 的重要性
3.坏注释 自言自语
多余的注释。把逻辑在注释里写一遍不能比代码提供更多信息，读它不比读代码简单。一目了然的成员变量别加注释，显得很多余。
误导性注释
遵循规矩的注释。每个函数都加注释、每个变量都加注释是愚蠢的。
日志式注释。有了代码版本控制工具，不必在文件开头维护修改时间、修改人这类日志式的注释
能用函数或者变量表示就别用注释:
// does the module from the global list <mod> // depend on the subsystem we are part of? if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()) 可以改为
ArrayList moduleDependees = smodule.getDependSubsystems(); String ourSubSystem = subSysMod.getSubSystem(); if (moduleDependees.contains(ourSubSystem)) 位置标记。标记多了会被我们忽略掉: ///////////////////// Actions //////////////////////////
右括号注释
try { while () { if () { ... } // if ... } // while ... } // try 如果你想标记右括号，其实应该做的是缩短函数
署名 /* add by rick */ 源代码控制工具会记住你，署名注释跟不上代码的演变。
注释掉的代码。会导致看到这段代码其他人不敢删除
信息过多。别在注释中添加有趣的历史话题或者无关的细节
没解释清楚的注释。注释的作用是解释未能自行解释的代码，如果注释本身还需要解释就太遗憾了。
短函数的函数头注释。为短函数选个好名字比函数头注释要好。
非公共API函数的javadoc/phpdoc注释。
