《代码整洁之道》读后总结 -- 关于注释

关于注释的简单思考：

• 注释的目的，在于使代码查看者能够快速的理解代码表达意思。
• 而表达意思的有：代码 + 注释 + 程序结构 + ...
• 程序的结构一定有安排好，取决于分类管理，组织能力。
• 代码的表达力：通过命名，清晰的逻辑，适当的模块化表现出来。
• 注释一方面用来弥补代码表达力的缺陷（KEY），另一方面用来自然语言快速表达意思。但注释本身就存在着一些缺陷，比如说：让程序的结构混乱，自然语言表达的不准确引起错误理解。
  

摘自《代码整洁之道》

1.注释总述

1.1.注释的恰当用法 是弥补我们在 用代码表达意图时遭遇的失败。

1.2 .注释会撒慌。

• 注释存在的越久，离其所描述的代码越远，越来越变得错误。 （ reason :程序员不能坚持维护注释）
  
• 代码在变动，演化。但是注释不一定。导致代码与注释演化的不同步，从而给程序员造成理解上的错误。

1.3.我们要尽量减少注释量。

• 将更多的精力放在代码表达力上。
  
• 代码能忠实告诉我们它做的事情。
• 注释不能美化糟糕的代码。
  
• 与其花时间为糟糕的代码注释，不如花时间 清洁糟糕的代码。

2. 好的注释

例子 ： 标准java库中的javadoc是好注释的例子。（学习其注释的风格，但不要在自己程序上全部注释）

2.1.法律信息

• 一般，公司代码规范要求编写与法律相关的注释。（如：版权，著作权）

2.2.提供信息的注释

• 用注释来提供基本的信息也有其用处。

2.3.对于意图的解释

• 注释不仅体现了有关现实的有用信息【功能，用法等】，并且体现了某个决定后面的意图【目的】。

2.4.阐释

• 注释把某些晦涩难懂的参数或返回值的意义 解释 为 某种可读形式。

• 尽量使用命名来表达意思，若不能修改参数名等（库函数），在考虑使用阐释。
  

2.5.警示

• 用于警告其他程序员会出现某种后果的注释。（比如说：某个方法会消耗大量时间）

2.6.TODO注释

• 用来在源码中放置要做的工作列表。（将来打算做什么？为什么还没做？）

2.7.放大

• 注释可以用来放大某种不合理之物的重要性。

3.坏的注释

3.1. 喃喃自语

• 如果需要添加注释，就有必要写出最好的注释。【表意清晰】
• 如果作者喃喃自语，表达不清楚自己的想法（对于作者来说可能有意义），对于后续工作者来说将是一个谜团。

3.2.多余的注释

• 注释若不能提供比代码本身更多的信息，并且读它并不比读代码容易。
• 注释不如代码精确，甚至可能误导读者。

3.3.误导性注释

• 不精确的注释有误导作用。所以代码的注释，一定要反复斟酌。

3.4.循规式注释

• 每个函数都有javadoc , 每个变量  都有注释的 规矩是愚蠢可笑的。（这种注释让代码变的散乱，不易让人理解）

3.5日志式注释

• 每次编辑代码，都在文件头部写注释。（类似于日志）【因为版本控制器的存在，应该抛弃这种方式】

3.6.废话注释

• java语法中包含的信息（再次用注释表现）等，重复已经众所周知的内容。

3.7.能用函数或者变量时就不要注释

3.8.归属与签名

• 已经被版本控制系统替代。

3.9.注释掉的代码

• 直接把代码注释掉很让人恶心，造成混乱。
• 会导致后来的代码维护者 不敢 删除注释掉的代码。（越累计越多）
• 有些注释代码可能后来确实会用到，但是现在 版本控制器 可以做到。

3.10.信息过多

• 代码中注释的信息，应该是简单的，有针对性的。
• 不要在注释中讲故事，以及一些不相关的事情。

3.11.不明显的联系

注释和代码之间的联系，应该是显而易见的。