【04】CC - 注释

为什么80%的码农都做不了架构师？>>>   

1、注释越久就越容易远离其描述的代码

     代码在变动，在演化，但是注释并不总是随之变动的，容易出现分隔，其描述越来越不准确，也带来了维护成本。最好就是用代码描述好事情。

2、注释不能美化糟糕的代码

     写注释的动机之一是糟糕代码的存在。带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样的多，与其花时间编写解释你搞出的糟糕的代码的注释，还不如花时间清洁那堆糟糕的代码。

3、最好的注释是用代码表达

    唯一真正好的注释是你想办法不去写的注释。尽量利用函数名称传达信息。

4、警示

    用于警告其他程序员会出现某种后果的注释是有用的。

    它可以用来放大某种看起来不合理之物的重要性。

5、坏注释

    坏注释是糟糕代码的支撑或者借口，或者对错误决策的修正，基本上等于程序员自说自话。

（1）喃喃自语

public void loadProperties(){
   try{
      ....
      loadedProperties.load(propertiesStream)
   }catch(IOException e){
      //no properties files means all defaults are loaded
   }
}

  上面这段，catch的异常一般能描述出问题，无需在重复描述，而描述的不清晰。

（2）多余的注释

  比如给每个属性前头都强制加了个注释，如果本身变量名足以描述，就没有必要添加注释了。

（3）误导性注释

   注释的信息与实际方法的描述相反，容易产生误导与困惑

（4）循规式注释

    例如Javadoc给每个变量/方法都强制加个注释

（5）日志式注释

   在注释里头标记每次修改的记录，这个可以用源代码版本工具替代掉。

（6）废话注释

    比如/** default constructor */

（7）可怕的废话

   比如Javadoc的

/** the name */
private String name;

（8）能用函数或变量时就不用注释

//does the module from the global ....
if(module.getDependSubsystems().contains(subSysMod.getSubSystem()))

   改成

List moduleDependees = module.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if(moduleDependees.contains(ourSubSystem ))

（9）位置标记

  比如// actions /

（10）括号后面的注释

 如果你想标记右括号，其实你应该做的是缩短函数。

（11）归属与署名

/** added by xxx*/  这种还是用源代码版本控制。

（12）注释掉的代码

      其他人不敢删除注释掉的代码，他们会想，代码依然放在那儿，一定有其原因，而且这段代码很重要，不能删除，注释掉的代码堆积在一起，就像破酒瓶底的渣滓一样。

（13）html注释

 如果是要文档，还是交给工具去处理。html注释容易使得代码难以阅读。

（14）非本地信息

如果要写注释，请离你要注释的代码最近，不要离得太远。

（15）信息过多

别在注释里头添加有趣的历史性话题或者无关的细节。

（16）不明显的联系

注释及其描述的代码之间的联系应该是显而易见的。

（17）函数头

短函数不需要太多的描述。

（18）非公共代码中的Javadoc

非公共代码，就不必为其生成Javadoc

转载于:https://my.oschina.net/scipio/blog/291315