第四章 - 注释 - 读书心得

”别给糟糕的代码加注释 --- 重写吧“  --- Brian W.Kernighan & P.J.Plaugher

注释不是万能的，良好的代码是不需要注释再做额外的解释的。

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。为什么是“失败”呢，因为注释说明了，代码无法清楚地表达自己。

为什么不提倡注释？ - 因为注释会撒谎的。

1. 注释的可维护性差，很多时候我们更改代码是不会去更改注释的，这就造成注释存在时间越久，就离其描述的代码越远，最好完全就是错误。

2. 程序员不能坚持维护注释。

3. 注释没有标准化

4. 太多无用的注释，使代码阅读变得困难。

- 曾看到给类中的每个成员，每个函数加注释的，无用的重复解释，只为了格式化，这导致一个类变得很大，原来可以一眼贯穿的类结构，变得很臃肿。

5. 再好的注释也比不上代码，因为代码才是真正的实现

1. 注释不能美化糟糕的代码

如果我们阅读代码时，觉得代码紊乱，没有注释无法阅读时，我们要做的不是增加注释还是整理代码

2. 用代码来阐述

有时，代码不足以说明其行为。这时，我们可以通过创建一个描述与其行为一致的函数就可以解决问题。

3. 好注释

有些注释是必须的，也是有利的。下面是一些值得写的注释

- 法律信息。 例如，版权及作者权声明就是必须和有理由在每个源文件开头注释处放置的

- 提供信息的注释。   用注释提供基本信息。

- 对意图的解释。 注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。

- 阐释。 注释把某些晦涩难名的参数或返回值的意义翻译成某种可读形式

- 警示。 用于警告其他程序员会出现某种后果的注释也是必须的。

- TODO注释。 TODO是程序员认为需要做，但没有做的工作。

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

- 公共API的DOC。 在公共API中用作API的Doc

4. 坏注释

- 喃喃自语。

-不要觉得应该或者因为流程而添加注释，如果要写就认真写，并花时间确保写出最好的注释。

- 注释最重要的旨在写给其他程序员看，所以不要写只有自己才能读懂的注释

- 多余的注释。

- 注释要不证明代码的意义，要不给出代码意图和逻辑...。如果注释本身没有价值那就是多余

- 误导性注释

- 循规式注释

- 遵循某种规则，结果导致一堆废注释。只为了规则。

- 日志注释

- 在文件开以日志的方式，记录文件修改日志。再想这样的价值几何，为什么不用版本管理工具。

- 废话注释

- 见过给类的构造函数加注释/*Default constructor*/的。无语。

- 能用函数或者变量时就别用注释

- 能不用注释就不用注释，让其他程序员直接关注代码而不是注释

- 位置标记

- ///////////////////////////////////////////////////////////////////////////////////////

- /*------------------------------------------------------------*/

- ..这类注释不要出现在代码中

- 括号后面的注释

- 在for while if的{}后面加//for or while or if

- 这只在长函数的时候有些作用，但是指望这种注释只为给我们写更长的函数找借口

- 如果函数足够小，自然没有这种需要

- 归属与署名

- /* Feature ID xxxx, add by xxx*/

- 同样为什么不使用版本控制工具？多年后author可能都不在了，注释还有什么用呢？

- 注释掉的代码

- 同样你的各种想法，版本控制工具都能为你提供

- HTML注释

- 没太多见过

- 非本地信息

- 信息过多

- 注释也要精简，并非越多越好

描述了这么多什么是有用的注释什么是无用的注释，说到底就几个字

clear, little, meaningful, descriptive