第五章 该写什么样的注释

关键思想：注释的目的是尽量帮助读者了解得和作者一样多。

当你写代码时，你的脑海里会有很多有价值的信息。当其他人阅读你的代码时，这些信息已经丢失----他们所见的只是眼前的代码。要知道什么时候应该把你脑海中的信息记录下来。

1.什么不需要注释

关键思想：不要为那些从代码本身就能快速推断的事实写注释。

• 不要为了注释而注释

• 不要给不好的名字加注释--应该把名字改好 好代码>坏代码+好注释

2.记录你的思想

• 对于为什么代码写成这样而不是那样的内在理由("指导性批注")

• 为代码中的瑕疵写注释

• 给常量加注释--常量背后的故事，为什么是这个值

3.站在读者的立场思考

• 预料到代码中哪些部分会让读者说：“啊？”并且给他们加上注释；

• 为普通读者意料之外的行为加上注释；

• 在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的；

• 用注释来总结代码块，使读者不致迷失在细节中。

克服“作者心理阻滞”

1.不管心里想什么，先把它写下来；

2.读一下这段注释，看看有没有什么地方可以改进；

3.不断改进。

第六章 写出言简意赅的注释

关键思想：注释应当有很高的信息/空间率。

如何把更多的信息装入更小的空间：

• 当像“it”和“this”这样的代词可能指代多个事物时，避免使用它们；润色粗糙的句子；让注释保持紧凑；

• 尽量精确地描述函数的行为；

• 在注释中用精心挑选的输入/输出例子进行说明；

• 声明代码的高层次意图，而非明显的细节；

• 用嵌入的注释(如Function(/*arg=*/...))来解释难以理解的函数参数；

• 用含义丰富的词来使注释简洁。