Question

现在你知道了什么不需要注释，下面讨论什么需要注释（但往往没有注释）。

很多好的注释仅通过“记录你的想法”就能得到，也就是那些你在写代码时有过的重要想法。

加入“导演评论”

电影中常有“导演评论”部分，电影制作者在其中给出自己的见解并且通过讲故事来帮助你理解这部电影是如何制作的。同样，你应该在代码中也加入注释来记录你对代码有价值的见解。

下面是一个例子：

//出乎意料的是，对于这些数据用二叉树比用哈希表快40%

//哈希运算的代价比左/右比较大得多

这段注释教会读者一些事情，并且防止他们为无谓的优化而浪费时间。

下面是另一个例子：

//作为整体可能会丢掉几个词。这没有问题。要100%解决太难了

如果没有这段注释，读者可能会以为这是个bug然后浪费时间尝试找到能让它失败的测试用例，或者尝试改正这个bug。

注释也可以用来解释为什么代码写得不那么整洁：

//这个类正在变得越来越乱

//也许我们应该建立一个'ResourceNode'子类来帮助整理

这段注释承认代码很乱，但同时也鼓励下一个人改正它（还给出了具体的建议）。如果没有这段注释，很多读者可能会被这段乱代码吓到而不敢碰它。

为代码中的瑕疵写注释

代码始终在演进，并且在这过程中肯定会有瑕疵。不要不好意思把这些瑕疵记录下来。例如，当代码需要改进时：

//TODO：采用更快算法

或者当代码没有完成时：

//TODO（dustin）：处理除JPEG以外的图像格式

有几种标记在程序员中很流行：

你的团队可能对于是否可以使用及何时使用这些标记有具体的规范。例如，TODO：可能只用于重要的问题。如果是这样，你可以用像todo：（小写）或者maybe-later：这样的方法表示次要的缺陷。

重要的是你应该可以随时把代码将来应该如何改动的想法用注释记录下来。这种注释给读者带来对代码质量和当前状态的宝贵见解，甚至可能会给他们指出如何改进代码的方向。

给常量加注释

当定义常量时，通常在常量背后都有一个关于它是什么或者为什么它是这个值的“故事”。例如，你可能会在代码中看到如下常量：

这一行看上去可能不需要注释，但很可能选择用这个值的程序员知道得比这个要多：

现在，读代码的人就有了调整这个值的指南了（比如，设置成1可能就太低了，设置成50又太夸张了）。

或者有时常量的值本身并不重要。达到这种效果的注释也会有用：

还有这样的情况，它是一个高度精细调整过的值，可能不应该大幅改动。

在上述所有例子中，你可能不会想到要加注释，但它们的确很有帮助。

有些常量不需要注释，因为它们的名字本身已经很清楚（例如SECONDS_PER_DAY）。但是在我们的经验中，很多常量可以通过加注释得以改进。这不过是匆匆记下你在决定这个常量值时的想法而已。