整洁代码之道 4 注释

还是认为这一章中作者对于注释的态度有点过于理想了，所以内容仅供参考

Tips

1. 若编程语言足够有表达力，或者我们擅长用这些语言表达意图，就不那么需要注释，也许是根本不需要
   • 我认为，如果注释能够清晰的表达代码的含义，对于回顾一些过去的项目是非常好的
2. 注释的恰当用法是弥补我们再用代码表达意图时遭遇的失败
3. 注释常常会与其所描述的代码分隔开来，越来越不准确
   • 所以在维护代码的同时，也要相应的维护注释，防止注释和代码被分隔
4. 程序员应当负责将注释保持在可维护、有关联、精确的高度

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

1. 带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样的多

4.2 用代码来阐述

1. 很多时候，只需要在函数名称上讲功能描述清楚，就可以省去一段注释

4.3 好注释

1. 有些注释是必须的，也是有利的

4.3.1 法律信息

1. 公司代码规范要求编写与法律有关的注释

4.3.2 提供信息的注释

1. 用注释来提供基本信息

4.3.3 对意图的解释

1. 注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图

4.3.4 阐释

1. 注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式

4.3.5 警示

1. 用于警告其他程序员会出现某种后果的注释

4.3.6 TODO 注释

1. 用 // TODO 形式在源代码中放置要做的工作列表
   • 例如某个代码结果中打算做到某个扩展，但是现在没做
   • 按照现代 IDE 的功能，在每次提交代码时，都会给予提示

4.3.7 放大

1. 注释可以用来放大某个看来不合理之物的重要性

4.3.8 公共 API 中的 Javadoc

1. 没有什么比被良好描述的公共 API 更有用和令人满意了

4.4. 坏注释

1. 都是糟糕代码的支撑或借口，或者是对错误决策的懒散修正，基本上都是这类程序员的自说自话，没有什么效果

4.4.1 喃喃自语

1. 如果你决定写注释，就要花必要的时间确保写出最好的注释
2. 任何迫使读者查看其它模块的注释，都是怀注释

4.4.2 多余的注释

1. 读注释花的时间比读代码花的时间还要长

4.4.3 误导性注释

1. 对代码描述不够精准

4.4.4 循规式注释

1. 所谓每个函数都要有 Javadoc 或每个变量都要有注释的规矩完全是个笑话

4.4.5 日志式注释

1. 在每次编辑代码时，都在模块开始处添加一条时间注释，这个已经没必要了，因为现在都有 代码版本控制系统（ Git ）

4.4.6 废话注释

1. 对于显而易见的事喋喋不休，毫无新意

4.4.7 可怕的废话

1. Javadoc 很有可能是废话

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

1. 有时候为了把代码写的简洁，而进行了很长的嵌套，但是又担心别人看不懂，所以加了一些注释
2. 这样的做法其实是本末倒置，不如直接把代码拆分出来写清楚

4.4.8.1 Bad Example

// 描述了下面这串代码的作用
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { … }

4.4.8.2 Good Example

1. 将代码拆分后，层次变的更分明，更容易理解，注释也显得无关紧要了

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { … }

4.4.9 位置标记

1. 尽量少用标记栏，只在特别价值的时候用

4.4.10 括号后的注释

1. 如果发现自己想标记右括号，这就说明应该缩短函数，将这一段代码迁移到外部，单独作为一个函数在引入此处

4.4.11 归属和署名

1. 代码版本控制系统非常善于记住 谁在何时添加了什么
2. 没必要用那些各种格式的注释搞脏代码
3. 代码版本控制系统才是这类信息最好的归属地

4.4.12 注释掉的代码

1. 直接把代码注释掉是非常恶心的做法
2. 可能当时你从某处复制过来一整段业务代码，但你只需要其中一部分，对于不需要的那些，暂时也没法确定以后需不需要（极大可能是因为懒得思考）
3. 首先从其他地方复制整段代码就不是一个好兆头，其次如果非要复制，请一定搞清楚用途，留下需要的，删掉多余的，而不是注释多余的

4.4.13 HTML 注释

1. 源代码注释中的 HTML 标记是一种废物

4.4.14 非本地信息

1. 请确保注释描述了离它最近的代码
2. 不要在本地注释的上下文环境中留下完全不相干的信息

4.4.15 信息过多

1. 别再注释中添加无关的细节描述，没人有耐心去看完整段整段的注释内容
2. 注释应该保持简洁的风格

4.4.16 不明显的联系

1. 注释及其描述的代码之间的联系应该是显而易见的
2. 注释的存在就是为了帮助理解，而不是混淆本意
3. 注释的作用是解释未能自行解释的代码，如果注释本身还需要解释，就很无语了

4.4.17 函数头

1. 短函数不需要太多描述
2. 为只做一件事的短函数选一个好名字，要比写函数注释好的多

4.4.18 非公共代码的 Javadoc

1. 虽然 Javadoc 对于公共 API 非常有用，但对于不打算作公共用途的代码就令人厌恶了

4.4.19 范例

1. 列举了作者自己的一段代码优化效果