《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