《代码整洁之道》第4章 注释 - 笔记

注释的恰当用法是弥补代码表达意图时遭遇的失败，良好的代码，让读者看代码就能明白含义。

代码在变动，在演化。注释并不总是随之变动。不准确的注释比没有注释要坏的多。注释算的上是一种没办法去除的恶。

注释不能美化代码

与其花时间编写解释你搞出糟糕代码的注释，不如花时间清洁那堆糟糕的代码

用代码阐述

省略注释，用代码代替，很多时候只需要创建一个描述与注释所言同一事务的函数即可。

好的注释

• 版权及著作权声明的注释
• 解释抽象方法返回值，不过这也能利用函数名表达，比如：

又比如：

把这代码移交给某个转换日期和时间格式的类中，注释显得就是多余。

• 对意图的解释，解释写某个功能、某个函数的意图
• 阐释返回值或者参数，能不用注释就不用。
• 警示其它程序员
• todo ，todo 应该解释为什么该函数部分无所作为，将来应该是怎样

• 放大某种看来不合理之物的重要性，强调这段不合理代码的重要性。如：

 

坏注释

坏注释是对糟糕代码的支撑、借口，或者对错误决策的修正

• 喃喃自语，可能对未来的自己写了一点不明确的注释，让外人看着很迷惑，未来自己看到也迷惑
• 多余的注释
• 误导性注释，语句有时难以精确用注释阐述，会漏掉一些信息或者含义有失偏颇。注释的意思要足够明确，假如代码出现2个数字，而注释没解释好，就会让人混乱。

• 循规式注释，每个函数都要有 javadoc 或者每个变量要有注释的规矩简直可笑！
• 日志式注释，在每个模块、新功能开始出添加一条注释，这种冗长的记录只会让模块变得凌乱不堪，应当全部删除
• 废话注释，对显然意思加以注释，喋喋不休。
• 能用函数或变量就别用注释，如下：

• 位置标记注释，比如一排--------，如果比较少还可以，如果多了那就乱七八糟。
• 被注释的代码，有了 git 和 ide 的历史版本，代码丢不了，尽管删！
• 注释过多，别把一些和代码无关的注释写上，如果要写注释，一定要精炼。别写故事！