《代码整洁之道》摘录---注释

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。我们总无法找到不用注释就能表达自我的方法，所以总要有注释，这并不值庆贺。

如果你发现自己需要写注释，再想想看是否有办法翻盘，用代码来表达。

注释会撒谎。注释存在的时间越久，就离其所描述的代码越远，可能变得全然错误。原因很简单：程序员不能坚持维护注释。

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

真实只在一处地方有：代码。只有代码能忠实地告诉你它做的事，所以应当减少注释。

写注释的常见动机之一是糟糕的代码的存在。我们编写一个模块，发现它令人困扰、乱七八糟。我们告诉自己：最好写点注释。不！最好是把代码弄干净!

比如 if ( (dataType>>24) &0x0f == 1)

dataBits = 24; //Color

else if (dataType>>24 & 0x0f == 2)

dataBits = 8; //Grayscale

else

dataBits = 1;//Black and White

就可以改为:

colorType = (dataType>>24)&0x0f;

switch(colorType)

{

case COLOR:

dataBits = 24;

case GRAYSCALE:

dataBits = 8;

case BLACK_WHITE:

default:

dataBits = 1;

}

TODO注释一定要定期查看，删除不再需要的，不然可能会变成一堆垃圾。

坏注释

1.自言自语

自己为标注某些未完成工作所加的注释。

2. 外余的注释

有时注释读起来比读代码还费劲。比如MicroSoft提供的一些例程,有时还不如先看MSDN。

3. 误导性注释

4.循规式注释

为所有函数和变量都加上Doxygen格式的注释显然不是什么好主意。

5. 日志式注释

使用SVN之类的版本控制软件更为合理。

6. 废话注释

比如

/**

* Default constructor

*/

MyClass::MyClass()

{

......

}

7.代码中的签名

8. 注释掉的代码