代码注释

代码整洁之道
第4章 注释
1、注释是为了弥补代码表达时的失败；
   尽量用清楚的代码表达意图，而不是使用注释（虽然注释不可避免），因为程序员不能坚持维护注释；
   唯一真正好的注释是你想办法不去写注释；
2、好注释：
   （1）法律信息；
        ----版权信息等；
   （2）提供信息的注释、对意图的解释；
        ----总体注释，函数作用的注释，语句块作用的注释等；
   （3）阐释；
        ----晦涩参数或变量的注释；
   （4）警示；
   （5）TODO注释；
       ----程序员认为应该做，但由于某些原因目前还没有做的工作；
3、坏注释：
   （1）多余的注释、废话注释；
    ----没必要仅仅因为需要而写注释；
    ----代码很清楚的不用写注释；
   （2）误导性注释；
    ----要么不写，要么就写准确；
   （3）循规式注释；
    ----要求每个函数都有javadoc式的注释、每个变量都有注释是愚蠢可笑的；
   （4）日志式注释；
    ----我们现在已经有了功能完备的版本控制工具，不要在每次编辑代码时都加包括日期、作者等信息的add、delete、modify信息；
   （5）右括号后面的注释；
    ----如果你发现由于嵌套太深而需要使用右括号后面的注释，你应该要做的是缩短函数；
   （6）确认不要的代码应该删除而不是注释掉；

高质量程序设计指南C++/C语言
第10章 C++/C文件结构和程序版式
10.3.6  注释风格
1、注释只是提示，不必过多，清楚的代码不用注释；
2、修改代码的同时要修改注释，使注释与代码同步，否则错误的注释比没有注释害处更大；
3、注释应当准确、易懂，防止出现二义性。