代码整洁之道(四)

第四章，注释

 

4.1 注释不能美花糟糕的代码。

写注释的常见动机之一是糟糕代码的存在，与其花时间解释你搞出的糟糕的代码的注释，不如花时间清洁那些那堆糟糕的代码。

 

4.2用代码来阐述。

用代码来解释你的意图，从函数命名上，创建一个描述与注释所言同一事务的的函数即可。

 

 4.3好注释。

4.3.1 法律信息，不应放代码中。

4.3.2 提高信息的注释，对抽象函数的返回值，有时管用，但是尽量利用函数名称来传达信息。

4.3.3对意图的解释。

4.3.4阐释

有时，注释把某些晦涩难明的参数或返回值的意义翻译为某种可读的方式，这是由风险的。

 

4.3.5 警示

用于警告其他程序员会出现某种后果的注释，这是有用的。

4.3.6 ToDo注释。

将要干什么，程序员应该做，但是由于某些原因没有做的工作。

这些注释要定期查看，删除不需要的。

4.3.7 放大

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

 

4.4坏注释。

4.4.1 喃喃自语。

只是个人觉得应该写就添加的话那是无谓之举。如果你决定加注释，就必须花时间确保写出最好的注释。

4.4.2多余的注释。

4.4.3误导性注释

4.4.4循规式注释

每个函数都要对每个变量进行注释，这是错误的。

4.4.5 日志性注释。

有人在每次编译代码时，都在模块开始添加一块注释，这类注释就像是一种记录每次修改的日志。

 

4.4.8 能用函数和变量时就别用注释。

4.4.9位置标记

4.4.10 括号后面的注释

） //end of while

)//end of if

4.4.11归属和签名。

/*added by rick*/

源码管理器非常善于记住是谁在何时添加了什么。没必要用那些小小的签名搞乱代码。

4.4.12 注释掉的代码。

代码注释掉的，直接删除

4.4.13 HTML注释

尽量避免

4.4.14非本地信息。

注释尽量靠近最近的代码。

4.4.15 信息过多。

注释不是越多越好。别添加有趣的历史性问题或无关细节的描述

4.4.16 不明显的关系。

注释与代码之间的关系应该显而易见。

4.4.17 函数头

短函数不需要太多描述，为只做一件事的短函数选个好名字，通常比写函数头注释要好。