阅读笔记08

阅读笔记08--代码整洁之道

第四章 注释

程序员应当负责将注释保持在可维护、有关联、精确的高度。作者同意此，但他更主张把力气用在写清楚代码上，直接保证无需编写注释

有时多花几秒钟，只需创建一个描述与注释所言同一事物的函数即可，此时代码就能解释大部分意图

4.1 好注释

1、法律信息，列如版权及著作权声明等

2、提供信息的注释，更好的方式是尽量利用函数名传达信息

3、对意图的解释

4、阐述（如将晦涩难懂的参数或返回值的意义翻译为某种可读形式，更好的方式是尽量让参数或者返回值自身足够清楚）

5、警示 （警告其他程序员会出现某种后果的注释）

6、公共API中的Javadoc

4.2 坏注释

1、喃喃自语 ，无必要的注释

2、多余的注释，如简单函数头部位置的注释

3、误导性注释

4、循规式注释

5、日志式注释（记录修改）

6、废话注释 （用整理代码的决心替代创造废话的冲动吧）

7、位置标记 （//Actions）

8、括号后面的注释 （如循环方便查看语句块，}结束于哪一个）

9、归属与署名 （/* Added by Rick */）

10、注释掉的代码 （别这么干！相信自己，可以删！）

11、信息过多

12、不明显的联系

13、函数头 （短函数不需要太多描述，好的函数名重于好的注释）

 

第五章 格式

好的代码格式可以让自己看起来舒畅，让别人读起来舒心。下面主要从垂直横向格式来介绍，其他的简单说明下

5.1 垂直格式

1、向报纸学习 报纸的排版，大纲。若报纸只是一片长文或者是杂乱的故事碎片则没有读者对它感兴趣

2、概念间垂直方向上的区隔

3、适当的空白行能够让代码赏心悦目，往下读代码时，你的目光总会停留于空白行之后那一行

4、垂直方向上的靠近

5、紧密相关的代码应该互相靠近

6、垂直距离

7、变量声明应尽可能靠近其使用位置

8、实体变量应该在类的顶部声明

9、相关函数的顺序应按其逐级调用的自然顺序排列

10、概念相关的代码应放到一起。相关性越强，彼此之间的距离就该越短。

5.2 横向格式

1、每一行代码长度应尽量不需拖动滚动条，45字符最好（与显示屏和字符大小相关）

2、格式化工具

3、水平对齐

4、有效适当的缩进