Clean Code 读后感（四）

忙或者说懒了很久，虽然书看到10多章了，但是却一直没来得及更新。来看看第四章吧。

陈旧、提供错误信息的注释最有破坏性。当然，跟不上变化的文档也是如此。

只有代码才能作为真正正确的信息来源。好的代码也许根本不需要注释。

让代码来表达意图，让代码来讲故事，让注释越少越好。

为什么注释如此的让人讨厌？

因为注释不一定会随着代码的更新而一同改变，到最后注释也许就会变得完全错误。

4.1 注释不能美化糟糕的代码

为糟糕的代码写注释不如对这些代码进行改善。程序员应该以代码为本，本末倒置是会付出代价的。

4.2 用代码来阐述

对代码进行重构可以极大的改善代码的表达能力。了解实现意图比了解实现细节更重要。

4.3 好注释

并非所有注释都一无是处，有些注释是必须的、有利的。

4.3.1 法律信息

强制要求，必须要加入到每个源文件里面。

现代IDE有相应的功能进行插入、折叠。注意其可扩展性。

4.3.2 提供信息的注释

最好能将这些信息与相关代码进行合并。比如对变量、函数等的解释不如更好、更清晰的命名。

4.3.3 对意图的注释

有时候代码不能反应出意图，这类注释在这些场合还是有用的。

4.3.4 阐释

尽量让代码本身清楚明了。如果是你不能左右的代码，可以写一些阐释的注释来帮助理解。

4.3.5 警示

这是注释绝对有用的一面。

4.3.6 TODO注释

IDE支持TODO注释，提醒程序员有哪些任务还没有做。最好还是一个TODO注释都没有。

4.3.7 放大

感觉和4.3.5警示差不多。

4.3.8 公共API中的Javadoc

良好的Javadoc编写不易，却能提供最好的支持。Javadoc与代码一定要同步，否则扯皮的事情就来了。

4.4 坏注释

回想起来自己以前写了很多坏注释，自己给给自己找了很多麻烦。

4.4.1 喃喃自语

话太多有时候是会惹祸的。

4.4.2 多余的注释

这些注释纯粹就是自找麻烦。

如果代码本身意图就很明显，也写得比较漂亮，就不需要这样的多余注释。

4.4.3 误导性注释

不能与代码精确匹配的注释将会给使用这段代码的调用者带来极大的痛苦。就像问路的时候问到了一个同样不熟悉路的人。

4.4.4 循规式注释

不需要每个变量、函数都有注释。

4.4.5 日志式注释

源码管理系统可以更好的完成这类注释的功能。

4.4.6 废话注释

4.4.7 可怕的废话

占用空间、资源，尽早删除为好。

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

4.4.9 位置标记

这类标记有时候其实有用，IDE对注释不同颜色的显示会让人感觉特别明显。

当然也不能滥用，只能在某些特别有价值的时候用。

4.4.10 括号后面的注释

出现这类注释，就说明嵌套可能太深了，应当进行重构了。

4.4.11 归属与署名

源码管理系统可以覆盖这样的需求。

4.4.12 注释掉的代码

写代码的过程也要进行回归，删掉那些不再使用的被注释掉的代码。

4.4.13 HTML注释

让注释更加复杂凌乱。注释也需要像代码一样保持整洁。

4.4.14 非本地信息

注释超越了被注释对象的范畴。

4.4.15 信息过多

注释要保持简单、短小，不要将外部材料也引入到注释中来。

4.4.16 不明显的联系

注释要与被描述的代码之间紧密联系，否则就是牛头不对马嘴了。

4.4.17 函数头

好的命名比函数头注释要好。

4.4.18 非公共代码中的Javadoc

没必要将细节也公开出来。

4.4.19 范例

整洁的写出良好的代码可以极大的减少不必要的注释。其实不需要太多的技巧，良好的命名就足以解决大部分问题。

注释的去留也不是所有时候都完全按照本章的规则来确定，例外是存在的，具体问题还得具体分析。