Question

阅读注释会占用阅读真实代码的时间，并且每条注释都会占用屏幕上的空间。那么，它最好是物有所值的。那么如何来分辨什么是好的注释，什么是没有价值的注释呢？

下面代码中所有的注释都是没有价值的：

这些注释没有价值是因为它们并没有提供任何新的信息，也不能帮助读者更好地理解代码。

关键思想

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

这里“快速”是个重要的区别。考虑一下下面这段Python代码：

从技术上来讲，这里的注释也没有表达出任何“新信息”。如果你阅读代码本身，你最终会明白它到底在做什么。但对于大多数程序员来讲，读有注释的代码比没有注释的代码理解起来要快速得多。

不要为了注释而注释

有些教授要求他们的学生在他们的代码作业中为每个函数都加上注释。结果是，有些程序员会对没有注释的函数有负罪感，以至于他们把函数的名字和参数用句子的形式重写了一遍：

这种情况属于“没有价值的注释”一类，函数的声明与其注释实际上是一样的。对于这条注释要么删除它，要么改进它。

如果你想要在这里写条注释，它最好也能给出更多重要的细节：

不要给不好的名字加注释——应该把名字改好

注释不应用于粉饰不好的名字。例如，有一个叫做CleanReply()的函数，加上了看上去有用的注释：

这里大部分的注释只是在解释"clean"是什么意思。更好的做法是把"enforce limits"这个词组加到函数名里：

这个函数现在更加“自我说明”了。一个好的名字比一个好的注释更重要，因为在任何用到这个函数的地方都能看得到它。

下面是另一个例子，给名字不大好的函数加注释：

DeleteRegistery()这个名字听起来像是一个很危险的函数（它会删除注册表？！）注释里的“它不会改动真正的注册表”是想澄清困惑。

我们可以用一个更加自我说明的名字，就像：

通常来讲，你不需要“拐杖式注释”——试图粉饰可读性差的代码的注释。写代码的人常常把这条规则表述成：好代码＞坏代码+好注释。