"注释"的注意事项--《Clean Code》笔记

《代码整洁之道》——“注释”

陈德胜 2013-12-27  整理

关于“注释”的一些原则：

1 注释不能美化糟糕的代码，与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码；

2 用代码本身来阐述其行为；

3 好注释包括：

       1）与法律相关的注释；

       2）提供基本信息的注释；

       3）对某个决定的意图的解释；

       4）对某些晦涩难明的参数或返回值的意义翻译为某种可读的形式；

       5）用于警告其他程序员会出现某种后果的注释；

       6）TODO注释，TODO是一种程序员认为应该做，但是还没有做的工作；

       7）放大某种看来不合理之物的重要性；

       8）公共API的说明文档；

4 坏注释包括：

       1）喃喃自语。如果你决定写注释，就要花必要的时间确保写出最好的注释；

       2）多余的注释；

       3）误导性的注释；

       4）循规蹈矩式注释。所谓每个函数或每个变量都要有注释的规矩全然是愚蠢可笑的；

       5）日志式注释。有人会每次编辑代码时，在模块开始出添加一条注释。这类注释就像是一种记录每次修改的日志，这种冗长的记录只会让代码变的凌乱不堪，应当全部删除；

       6）废话注释。用整理代码的决心替代创造废话的冲动吧，你会发现自己成为更优秀、更快乐的程序员；

       7）能用函数或变量时就别用注释；

       8）位置标记。有时候程序员喜欢在源代码中标记某个特别位置，但是这种标记尽量少使用，只在特别有价值的时候用；

       9）括号后面的注释。如果你发现自己想标记右括号，其实应该做的是缩短函数；

       10）归属和署名。源代码控制系统是这类信息最好的归属地；

       11）注释掉的代码。直接把代码注释掉是讨厌的做法，别这么干；

       12）非本地信息。假如你一定要写注释，请确保它描述了离他最近的代码；

       13）信息过多。别在注释中添加有趣的历史性话题或者无关的细节描述；

       14）不明显的联系。注释及其描述的代码之间的联系应该显而易见。如果你不嫌麻烦要写注释，至少让读者能看着注释和代码，并且理解注释所谈何物；

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