代码整洁之道 - 阅读笔记 （三）

#代码整洁之道 - 阅读笔记 （三）

第四章 注释

注释是一个比较微妙的存在。若编程语言足够有表达能力，就不需要注释。注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。原因在于：程序员往往不能坚持维护注释，导致注释和代码不符。

#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注释

TODO是应该做的，由于某些原因工作没有做完，提醒接下来要做的事情。

##4.3.7 放大

放大某种不合理之物的重要性。

##4.3.8 公共API的JavaDoc

良好的描述给公共API很高的阅读性，了解业务逻辑的重要途径。

#4.4 坏注释

##4.4.1 喃喃自语

只是因为作者应该或者过程需要，就添加注释，就是无谓之举！！！！非常容易犯错。例如：

##4.4.2 多余的注释

##4.4.3 误导性注释

##4.4.4 循规式注释

每个函数都要有JavaDoc或每个变量都要有注释的规矩是坏的。

##4.4.5 日志式注释

如下注释，不需要，没有意义。

##4.4.6 废话注释

##4.4.7 能用函数或变量时，就别用注释

##4.4.8 位置标记

少用特定位置的标记栏。

##4.4.9 括号后面的注释

##4.4.10 注释掉的代码

代码都注释掉了，就删除了吧

其他的注释，不太明显，或者本人认为是可以添加的，就不进行赘述。