（读书笔记）代码整洁之道-注释

代码整洁之道

注释

别给糟糕的代码加注释，重新写吧。

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。

1.注释不能美化糟糕的代码。
就是说，感觉需要写注释时先尝试优化代码。

2.用代码来阐述。
尽全力把代码写的简洁明了，再用注释解释。

3.好注释
1).法律信息(版权等等)
2).提供信息的注释
3).对意图的解释
4).阐释晦涩难懂的参数、返回值的意义
5).警示
6).定期清理TODO注释

4.坏注释
1).喃喃自语(注释是给读者看得不是给自己看得)
2).多余的注释(没有提够比程序本身更多的信息)
3).误导性注释
4).循规式注释
5).日志式注释
6).废话注释
7).标记位置 (例如：//看这里///////)
8).括号后边的注释
9).归属名
10).注释掉的代码
11).HTML注释（这里是指在注释中添加HTML标签，扰乱视线）
12).非本地信息（就是说你在注释中描写另一个代码块）
13).信息过多
14).不明显的联系(也就是说要写就写清楚)
15).函数头(一个好的函数名远远好于一个注释)
16).非公共代码中的javadoc

总结：还是说写好代码是关键，注释是辅助功能。
但是尽然写注释就一定要写简洁明了。