前段时间在组织代码review时，提到代码可读性问题时，很多人的第一反应竟然是多添加注释。而我始终觉得注释只能是锦上添花，而不能雪中送炭。再多的注释也改变不了代码逻辑组织混乱的现实，反而过多的注释会加重代码阅读的时间。
什么也比不上放置良好的注释来得有用；什么也不会比乱七八糟的注释更能搞乱一个模块；什么也不会比陈旧、提供错误信息的注释更有破坏性
注释是一种必须的恶，只有在编程语言表达能力不够时，我们才需要借助注释来说明代码含义。注释的恰当用法是用来弥补我们在代码表达意图时遭遇的失败。如果你发现自己需要写注释，那么可以思考一下，是否可以用代码来表达。
注释还有一个致命的缺点是，它不一定是对的。当我们在修改别人的代码看到他们的注释时，我们有极大的可能不会去修改他们的注释。如此日积月累，被注释的代码含义早已改变，但注释却没有随着代码的维护而被维护。
1、注释不能美化糟糕的代码
写注释的常见动机之一是糟糕代码的存在。
带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码易于阅读和维护得多。
2、用代码来阐述
比如下面这段代码，你更愿意看哪个：
3、好注释
有些注释时必须的，也是有利的。但是唯一真正好的注释时不需要注释就能表达的。
3.1 法律信息
3.2 提供必要信息的注释
3.3 对意图的解释
有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。
3.4 阐释
有时，注释把某些晦涩难懂的参数或返回值的意义翻译为某种可读形式。通常我们要尽量让参数或返回值自身表达足够清楚，但如果返回值或参数是某个标准库的一部分，我们不能修改源代码，这时可以用注释说明。
3.5 警示
用于警告其他程序员会出现什么样的异常后果
3.6 ToDo注释
ToDo是一种程序员认为应该做，但由于某些原因目前还没有做的工作。
3.7 放大
用于放大某种看来不合理之物的重要性
3.8 公共API的 java doc
这种注释我们在JDK的源码、spring源码中经常看到
4、坏注释
大多数注释都属于坏注释。通常，坏注释是糟糕代码的支撑和借口，或者是对错误决策的修正，基本上等于程序员自说自话。
4.1 喃喃自语
如果只是因为你觉得应该或者因为过程需要添加注释，那就是无谓之举。如果你决定写注释，就要花必要的时间确保写出好的注释。
4.2 多余的注释
比如下面这段代码：
注释不能比代码本身提供更多的信息。
4.3 误导性注释
如果写出的注释不够精确，反而会误导阅读代码的人。
4.4 循规式注释
所谓每个函数都要有Javadoc注释或每个变量都要有注释的规矩，很多时候让代码变得散乱，而且随着代码的迭代，如果注释没有更新，还会误导对代码的理解。
4.5 日志式注释
有人会在每次编辑代码时，在模块开始出添加一条注释，这类注释就像是一种记录每次修改的日志。如下面这样的注释：
4.6 废话注释
4.7 位置标记
有时程序员喜欢在代码中标记某个特别的位置， 如：
4.8 括号后面的注释
4.9 归属与签名
4.10 注释掉的代码
直接把代码注释掉是很糟糕的做法。后续维护程序的人不敢删除注释的代码，而注释掉的代码堆积在一起，会干扰代码的阅读，不利于代码维护和阅读。
4.11 HTML注释
4.12 非本地信息
假如要写注释，请确保它描述了离它最近的代码。
4.13 信息过多
4.14 不明显的联系
注释以及描述的代码之间的联系应该显而易见，至少让读者能看着注释和代码，能够理解注释所描述的东西。
4.15 函数头
函数不需要太多描述，为一个函数起一个好的名字，通常比函数头的注释要好得多。
4.16 非公共代码中的Javadoc
Javadoc对于公共API非常有用，但对于不撒算作公共用途的代码就是累赘。为系统中的类和函数生成Javadoc页并非总是有用，而javadoc注释额外的形式要求几乎等同于八股文章
小结：
- 能用函数或变量说明时，就不要用注释。
- 如果需要添加注释，先考虑是否可以重新组织代码、起一个合适的函数名或变量名
- 注释只有在必要的时候，再去添加。