代码整洁之道-第四章——读后感

代码整洁之道-第四章
前文：注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。（写注释之前需要想想是否能不用注释就可以表达代码的想表达的含义）
-------因为注释会撒谎，原因：程序员不能坚持维护注释。
-------建议把力气用在如何去写好代码上，而不是用在写注释上。
-------保持注释的可维护、有关联、精确的高度；

4.1 注释不能美化糟糕的代码

带有少量注释的整洁而有表达力的代码 > 带有大量注释的零碎而复杂的代码

4.2 用代码来阐述

代码量少的情况： 创建函数 > 注释
举例：

// Check to see if the employee is eligible for full benefits
if( ( employee.flags & HOURLY_FLAG ) && ( employee > 65 )

                                 ^

if ( employee.isEligibleForFullBenefits() )

4.3 好注释
有一些注释是必须的，也是有利的；（唯一真正好的做法是你想办法不去写注释）
1、法律信息：
版权著作权声明、作者、创建日期等等
-----------如果注释过多，就指向一份标准许可或其他外部文档。

2、提供信息的注释

3、对意图的理解

4、阐释
如果参数和返回值是某个标准库的一部分，或是你不能修改的代码，就可以写注释进行阐述。

5、警示

6、TODO注释
todo是一种程序员认为应该做，但是由于某些原因目前还没做的工作。
注意：需要定期查看，删除不在需要todo的注释。

7、放大
注释可以用来放大某种看来不合理之物的重要性。

8、公共API中的javadoc
如果你在编写公共API，就该为他编写良好的Javadoc。
建议：Javadoc也可能误导，不适合或者提供错误信息

4.4 坏注释
1、喃喃自语
如果决定写注释，就要花必要的时间来写出好的注释。

2、多余的注释
注释不能误导读者接受不精确的信息，

3、误导性的注释

4、循规式注释
每个函数都有Javadoc或每个变量都要有注释只会让代码变得散乱，误导读者。

5、日志式注解
含义：模块开始处添加一条注释，用来记录每次修改的日志。
注意：舍弃这种日志式注解

6、废话注释

7、可怕的废话

8、能用函数或变量时就别用注释

9、位置标记
不要滥用标记栏，（除了特别有价值的时候用）
举例： // Actions //

10、括号后面的注释
缩短函数来替代括号后面的注释

11、归属与署名
源代码控制系统 替代 归属与署名
源代码控制 (又称为版本控制) 是指跟踪和管理代码的更改。源代码控制管理 (SCM) 系统提供代码开发的运行历史,有助于在合并来自多个源的内容时解决冲突。

12、注释掉的代码
优良的代码控制系统会为我们记住不要的代码，我们无需再用注释来标记，删掉即可，可以通过代码控制系统找到。

13、HTML注释
尽量不要使用HTML注释，有工具可以将注释提取出来提取到界面。

14、非本地信息
假如你一定要写注释，请确保它描述了最近的代码。别再本地注释的上下文环境中给出系统级信息。

15、信息过多
别再注释中添加有趣的历史话题或者无关的细节描述。

16、不明显的联系
注释及其描述的代码之间的联系应该显而易见。

17、函数头
短函数不需要太多描述。
为只做一件事的短函数选个好名字 > 函数头写注释

18、非公共代码中的Javadoc

19、范例