哪里需要注释——《The-Art-of-Readable-Code》第五章导读

注释不只是为了解释一段代码的作用，注释是为了将代码编写者所知道的信息全部传达给阅读者。

当你编写代码的时候，你脑中会有很多有价值的信息，这些信息形成一个编写代码的思维环境。 最后，代码写完了，这些环境信息却丢失了。 当其他人阅读代码时，由于不在这个“环境”中，就很难理解那些代码。 注释要做的，就是让阅读者能根据注释提供的信息，还原这个“环境”。

不要注释什么

读注释会占用读代码的时间，显示注释还会占用屏幕上的空间，所以我们必须保证这些时间和空间物有所值。

不要注释一眼就可以从代码中看出来的东西。 有价值的注释必须提供一些无法一眼就能从代码中找到的信息。

不要为了注释而注释。 这常常会导致注释和代码表达重复的信息。

不要注释一个糟糕的命名。 你要做的是找一个更好的名字，名称就是对自己功能的最好注释。 命名要做到“自我解释”。 记住这个公式“ 好代码 > 坏代码 + 好注释 ”。

记录你的想法

当你写代码时，头脑中会有一些想法，比如为什么要这么做而不那么做，把他们记录下来。

引入“导评”。 “导评”是指你自己如何看待这段代码，包括这么写的用意、优势劣势等。 阅读者可以顺着你的思路来理解代码，避免出现疑虑。

注释代码中的缺陷。 有时候，我们知道代码中存在问题，但没有时间立刻修复，或者问题不大不急于解决，可以通过注释来进行标注。 使用标记可以防止我们漏掉一些问题，也可以用来帮助其他人理解这些有问题的代码，或者你已经有改进的思路了，也可以写下来避免自己或其他人重复思考这个问题。 常用的标记有 TODO 、FIXME 、HACK 等。

对常量进行注释。 说明常量为什么要取那个特定的值。

站在阅读者的角度看代码

站在一个完全不了解你的项目的人的角度看代码，可以帮助你找出哪里需要注释。

预测可能出现的疑问。 写完一段代码后，回过头来看看，其他人读代码时会对哪部分产生疑问。 比如不常用的语言特性、冷门的函数以及从特殊的角度思考问题产生的算法。 如果你觉得别人读到这里很可能会被卡一下，就应该有预见性的加上说明，帮他们渡过难关。

为可能被误用的功能加上注释。 很多时候开发者会想当然的使用一个函数，因为函数名看上去很清楚地交代了这个函数是做什么的。 但是函数名通常不会告诉你它将消耗大量内存或者需要很长时间来执行。 这时就该用注释来解释下函数的内部实现并给出适合使用的场景指南，从而避免其他人对函数的误用。

进行大局注释。 对一个项目的新成员来说，对项目的整体了解更为重要。 大局注释要做的就是站在更高的视角把一些整体性的信息展现出来。 在每个文件顶端用几行注释告诉阅读者这个文件是用来干什么的，要比让他看完整个文件后再自己总结要好多了。

总结出概括性的注释。 当一个函数中的内容较多时，可以把这个函数中的代码整理成相对独立的段落，并对这些段落进行概括性的注释，让读者能先了解这几个大的步骤，再去关心细节。 这样不仅便于理解，在需要时还能将这些段落提取成独立的函数以便复用。

培养写注释的习惯

很多开发者不写注释，并不是因为他们不喜欢注释，而是因为他们觉要把注释写好太难了。 最好的解决方法是直接把大脑中的想法记下来，不要担心这样的注释不够“专业”，注释的目的是为了传递信息。 想法一旦被写出来，就变得更容易分析和改进。 写注释的过程就是“写下来，分析，改进”。