注释

“别给糟糕的代码加注释——重新写吧。”
                          ——Brian W.Kernighan 与 P.J.Plaugher

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。所以注释并不是一种好东西，当我们要写注释时，应想办法找找能不能翻盘，从而使我们不通过注释就能表达清晰意图。

注释不能美化糟糕代码

我们写注释的动机之一是糟糕代码的存在。想通过注释来使之表意清晰。
但是请记住，带有少量注释的整洁而有表达力的代码，要比代有大量注释的零碎而复杂的代码像样的多。所以与其花时间为糟糕的代码写注释。不如花时间将它重构。

用代码来阐述

// check to see if the employee is eligible for full benefits
if ( (employee.flags & HOURLY_FLAG) && (employee.age > 65) )
//VS
if (employee.isEligibleForFullBenefits())

我们看上面两个指令：一个通过注释来表达意图，而另一个创建了一个函数，但表达了相同的意思，而我们只需思考几秒

好注释

有些注释时好的，也是有利的。下面是一些比较值得写的注释。但是请记住，真正好的注释时想办法不去写的注释。

1. 法律信息
   公司代码规范要求编写的与法律相关的注释。
   如果可以，这种注释应指向一份标准许或其他外部文档，而不是把条款放在注释中
2. 提供信息的注释
   有时用注释来提供基本信息也有其作用
3. 对意图的解释
   注释不仅提供了有关实现的有用信息，而且提供了某个决定后面的意图。
4. 阐释
   注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式。
5. 警示
   用于警告别的程序员会出现某种后果的注释。
6. TODO注释
   TODO是一种程序员认为应该做，但由于某些原因目前还未做的工作。
   TODO要定期查看，删除不需要的
7. 放大
   注释可以用来放大某种看起来不合理之物的重要性。
8. 公共API的Javadoc

坏注释

通常，坏注释都是糟糕代码的支撑或借口，或者对错误决策的修正。

1. 喃喃自语
   只是觉得应该添加或者过程需要就加注释。
2. 多余的注释
   不要让读注释的时间比读代码的时间还长。
3. 误导性注释
   虽然初衷是好的，但是写的不够精确地注释。
4. 循规式注释
   为函数或者变量加注释是愚蠢和可笑的。
5. 日志式注释
   记录每次修改的日志
6. 废话注释
   顾名思义，纯粹在讲废话的注释
7. 可怕的废话
   不知道干什么，只是随意的复制粘贴
8. 能用函数名或变量时就别用注释
9. 位置标记
   用于标记某个特殊位置
10. 括号后面的注释
    适用于深度嵌套结构的长函数，不适用于短小、封装的函数。
11. 归属与署名
    源代码控制系统非常善于记住是谁在何时添加了什么。所以不比较自己增加签名
    12.注释掉的代码
    没用的代码直接删掉，而不是注释。不然别人都不知道这段代码到底有没有用。
    13.HTML注释
12. 非本地信息
13. 信息过多
14. 不明显的联系
15. 函数头
16. 非公共代码中的javadoc