编写代码注释的最佳实践

[导读]关注、星标公众号，直达精彩内容来源：CSDN（ID：CSDNnews）作者：EllenSpertus| 译者：王雪迎虽然有很多资源可以帮助程序员编写更好的代码，比如书籍或静态分析器，但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易，但衡量注释的质量却很...

虽然有很多资源可以帮助程序员编写更好的代码，比如书籍或静态分析器，但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易，但衡量注释的质量却很难，而且两者并不一定相关。差的注释比根本不写注释更糟糕。这里有一些规则可以帮助你实现一种折中的方法。

麻省理工学院的著名教授Hal Abelson曾说过：“程序必须写给人们阅读，而只是附带地让机器执行。”虽然他可能故意低估了运行代码的重要性，但却注意到了程序有两种截然不同的受众。编译器和解释器会忽略注释，找出同等容易理解的所有语法正确的程序。而人类读者则完全不同。我们发现有些程序比其它的更难理解，此时就会通过查看注释来帮助我们理解这些程序。

虽然有很多资源可以帮助程序员编写更好的代码，比如书籍或静态分析器，但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易，但衡量注释的质量却很难，而且两者并不一定相关。差的注释比根本不写注释更糟糕。正如Peter Vogel所述：

编写并维护注释是一项开销。
编译器不会检查注释，因此无法确定注释是否正确。
另一方面，你可以保证计算机完全按照你的代码所示运行。

所有这些观点都是正确的，但如果走到另一个极端，即从不写注释，那将是一个错误。这里有一些规则可以帮助你实现一种折中的方法：

规则1：注释不应与代码重复。
规则2：好的注释不能成为代码不清晰的借口。
规则3：如果无法写出一个清晰的注释，代码可能有问题。
规则4：注释应该消除混乱，而不是引起混乱。
规则5：在注释中解释不规范的代码。
规则6：提供复制代码的原始出处链接。
规则7：在可能提供帮助的地方引入指向外部参考的链接。
规则8：在修复bug时添加注释。
规则9：使用注释来标记未完成的实现。

本文其余部分将逐条解释这些规则，提供示例并说明如何以及何时应用它们。

规则1：注释不应与代码重复

许多初级程序员会写太多注释，因为他们接受了入门指导老师的培训。我曾见过计算机科学系的高年级学生为每对大括号加上一条注释，以表示该块结束：

if (x > 3) { …} // if 我也听说过老师要求学生对每一行代码进行注释。虽然这对极为初级者来说可能是一个合理的策略，但这样的注释就像是训练轮，在大孩子骑车时应该去掉。

不添加任何信息的注释具有负价值，因为它们：

增加视觉混乱
读写花时间
可能会过时

一个典型的坏示例为：

i = i 1; // Add one to i 它不添加任何信息，并切产生维护成本。

每一行代码都需要注释的策略在Reddit上都受到了相当的嘲笑：

// create a for loop // <-- commentfor // start for loop( // round bracket // newlineint // type for declarationi // name for declaration= // assignment operator for declaration0 // start value for i

规则2：好的注释不能成为代码不清晰的借口

注释的另一个误用是提供本应包含在代码中的信息。一个简单的例子是，有人用一个字母命名一个变量，然后添加一个描述其用途的注释：

private static Node getBestChildNode(Node node) { Node n; // best child node candidate for (Node node: node.getChildren()) { // update n if the current state is better if (n == null || utility(node) > utility(n)) { n = node; } } return n;} 通过更好的变量命名，可以不需要再做注释：

private static Node getBestChildNode(Node node) { Node bestNode; for (Node currentNode: node.getChildren()) { if (bestNode == null || utility(currentNode) > utility(bestNode)) { bestNode = currentNode; } } return bestNode;} 正如Kernighan和Plauger在编程风格要素一书中所写，“不要注释糟糕的代码 — 重写它。”

规则3：如果无法写出一个清晰的注释，代码可能有问题

Unix源代码中最臭名昭著的注释是“你不希望理解它”，它出现在一些恐怖的上下文切换代码之前。Dennis Ritchie后来解释说这是故意为之：“本意是想表达‘这不会出现在考试中’，而不是作为一种厚颜无耻的挑战。”不幸的是，结果发现他与合作者Ken Thompson自己也理解不了，后来不得不重写。

这让人想起了Kernighan定律：

调试在一开始就比编写程序困难一倍。因此，按照定义，如果你的代码写得非常巧妙，那么你就没有足够的能力来调试它。

警告读者远离你的代码就像打开汽车的危险警示灯：承认你正在做知法犯法的事情。相反，把代码重写成你充分理解的东西，或者更进一步，直截了当地进行解释。

规则4：注释应该消除混乱，而不是引起混乱

如果没有Steven Levy的黑客：计算机革命的英雄中的这个故事，任何关于负面注释的讨论都是不完整的：

[Peter Samson]拒绝在源代码中添加注释来解释他在特定时间所做的事情，使其特别晦涩难懂。在一个分发良好的程序中，Samson继续编写了数百条汇编语言指令，其中只有一条包含1750数字的指令带有注释。注释是RIPJSB，人们绞尽脑汁研究它的含义，直到有人发现1750年是巴赫去世的那一年，而Samson写的注释是Rest In Peace Johann Sebastian Bach（安息吧，约翰·塞巴斯蒂安·巴赫）的缩写。

虽然我和别人一样欣赏一个好的黑客，但这种注释不可效仿。如果你的注释引起混乱而不是消除混乱，删除它。

规则5：在注释中解释不规范的代码

注释掉其他人可能认为不需要或冗余的代码是个好主意，比如来自App Inventor的代码（我所有的正面示例均源于此）：

final Object value = (new JSONTokener(jsonString)).nextValue();// Note that JSONTokener.nextValue() may return// a value equals() to null.if (value == null || value.equals(null)) { return null;} 如果没有注释，有人可能会“简化”代码或将其视为一个神秘但必不可少的咒语。写下为什么需要这些代码，可以节省未来读者的时间并解除他们的焦虑。

需要对是否注释代码做出判断。在学习Kotlin时，我遇到了Android教程中的代码：

if (b == true) 我立即想到是否可以用以下代码取代：

if (b) 就像在Java中一样。经过一点研究，我了解到可以为null的布尔变量会显式地与true进行比较，以避免出现难看的null检查：

if (b != null