还有何时需要注释？

在上篇文章中，我强调了注释的非必要性。今天重新反思了一下我设计和实现的过程，发现这篇文章还有一些需要补充的，才算完整。

在此之前，先说明一下在这两篇文章中，那些“真正”属于注释范畴的东西：既提供给作者和修改者看的，和代码放在一起的文本。

对于提供给使用者看的文本，比如上篇文章中提到的接口描述，无论是否采用了注释的形式，一概算作文档，不在讨论范畴之内。

对注释有帮助的情况的个人经验补充

引用一下上一篇文章说的两种情况：

1. 一句或一段代码抽象过了头，也许需要跟业务相关的描述建立一个直观的对应。

2. 因为安排的不够妥帖或者很难妥帖，一段逻辑中蹦出一句为不相关逻辑服务的代码。

实际上除了这些，还有两种场景让我去写注释：

3. 脑袋说的那种对接下来要实现的东西的描述，在我的代码中体现为“//TODO:”。

4. 另外一种情况，我自己认为这里有问题，但是暂时选择了不去修改它，体现为“//CAUTION:”。

这两种情况和上面两种是不同的。

这样的注释，会随着项目的进行和重构，一点一点的消失掉。最终我会Find in Files，确认这两个标记已经不在了。

无论如何，这也是注释，而且它们对我产生了帮助。还有什么是需要注释、或者说注释可以帮助我们的？

有一些代码留下这样的注释：“以下算法实现了论文xxxxxx，时间复杂度是m，另有论文yyyyy，时间复杂度为n”。

这就又多了一种情况：

5. 这种一句话交代背景、指向文档的注释也总是有作用的，它们是一种建立联系的索引。

这种注释和第一种有相似性，但又有所不同。

我相信还有其它类似的经验，希望掌握它们的兄弟为大家提个醒，让这个讨论变成建设性的，而不仅仅是一种辩论。

对上篇文章讨论的一些补充

那种描述逻辑的注释真的有用吗？按照脑袋的体验是有用的，但是我觉得这种经验确实不是放之四海皆准的；同样，注释无用论也不见得适合每一个人。

我个人仅仅是认为，让不写注释的兄弟去照顾写注释的，不像很多人想象的那样理所应当，这个上篇文章基本阐述清楚了我的想法。

对于这个问题，下面再补充一个我个人的经历，有兴趣的可以看看，没兴趣的可以跳过了。

大家可以先看一下这段代码，这是一个简单的使用javascript解析javascript语法子集的例子。当初我将这段代码翻译成python的，一共花费了1天左右的功夫。

在核心函数expression的注释上，我花了3个小时去写和改。按照我当时的认识，我会认为这是因为这段代码的复杂度要求我阐述其逻辑，我甚至举了一个精心的例子来描述其执行流程。

实际上昨天看这些代码(原装的和我翻译的)时，我真正的感受是，这个东西设计的真不咋地。假设当初我看到的是更好的设计和实现，我根本就不会花费那么时间和精力。

如果这段（原装的）代码是我身边的人写的，那么我会要求他去重构，而不是补上注释。事实上正是因为结构设计的不够优良，实现的也不清晰，才导致自己和别人产生理解上的种种障碍。

如果说当初我在翻译版本中留下的注释有什么作用，就是提醒我“这段相对其它内容比较复杂，需要仔细一点”。考虑我对自己原先写下的注释（肯定不是错误的）的反应，我不太相信它们能对其他人发挥什么良好作用。

这段代码的核心是递归下降与算符优先的结合，有人可能注意到了，其作者Douglas Crockford有比注释更详细的文本解释其来龙去脉。更多的内容还出现在《代码之美》之中，我第一次翻译的时候这个中文版就在我手边。

我要说的是什么呢？我不能说这些文本在当时对我一点帮助没有，但是我个人认为，即使如此详尽的文本，对阅读代码而言，也抵不上清晰可读的结构。

况且，对于一个有限的时间，我们能写出十好几页16开的注释吗？