《clean code 》 chap4注释

/**这个主题应该是,有意义的命名; 良好的注释习惯; 熟练的源代码控制系统; */      注释有其天然的问题:代码在变动,在演化。但程序员不能坚持维护注释。

4.1 注释不能美化糟糕的代码  【与其花时间编写解释你搞出的糟糕的代码的注释,不如花时间清洁那堆糟糕的代码。】

4.2 用代码来阐述    【创建一个描述与注释所言同一事物的函数即可】

4.3 好注释

  4.3.1 法律信息

  4.3.2  提供信息的注释

  4.3.3 对意图的解释

   4.3.4 阐述

    4.3.5 警示

  4.3.6 TODO注释

  4.3.7 放大

  4.3.8 公共API中的javadoc

4.4 坏注释

 4.4.1 喃喃自语

【如果只是因为你觉得应该或者因为过程需要就添加注释,那就是无谓之举。】

try

{

}

catch(IOException e)

{//No properties files means all defaults are loaded

}【任何迫使读者查看其它模块的注释,都没能与读者沟通好,不值所费】

4.4.2 多余的注释    【使用javadoc的话,要使注释有文档上的价值】

4.4.3 误导性注释

4.4.4 循规式注释   【每个函数都要有javadoc或每个变量都要有注释的规矩全然是愚蠢可笑的】----这需要函数和变量命名变得有意义,而不是随便命个名。

4.4.5 日志式注释

4.4.6  废话注释

/**The day of the month.*/   private int dayOfMonth;

4.4.7  可怕的废话

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

4.4.9 位置标记  【尽量少用标记栏,只在特别有价值的时候用】

4.4.10  括号后面的注释

4.4.11 归属与署名  /*Added by Rick*/【源代码控制系统是这类信息最好的归属地】

4.4.12 注释掉的代码  【直接把代码注释掉是讨厌的做法】-----直接从源代码挂管理系统里找

4.4.13 HTML注释

4.4.14 非本地信息

4.4.15  信息过多

4.4.16  不明显的联系

4.4.17  函数头

4.4.18  非公共代码中的javadoc   【javadoc对于API非常有用,但对于不打算作公共用途的代码就令人厌恶了】

4.4.19  范例

4.5   文献

The Elements of Programming Style

原文地址:https://www.cnblogs.com/wolflion/p/2883161.html