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

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

 

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

 

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

 

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

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

 

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

 

比如 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. 注释掉的代码