注释还是不注释，这是个问题

  • Abel Avram
  • 张龙

2010 年 3 月 11 日

话题：架构语言 & 开发文化 & 方法

每个开发者都曾在代码中写过注释，有些人的注释很多，为的就是更好地说明代码的意图。本文搜集了关于编写代码注释的一些实践以飨各位读者。

最近，Seattle Area Alt.Net小组的成员们就编写代码注释的必要性和实践进行了激烈的讨论。Kelly Leahy 坚持少写注释并编写能够自我说明的代码，因为他相信注释“只会向系统中引入不和谐的声音；一旦修改代码，那些注释就入土为安了”：

编写注释对于大多数人来说是个人的事情，但我本人非常反对写注释，因为一旦修改代码，那些注释就入土为安了——这种情况我见得太多了：注释还在那儿，但代码早就被删除了或是描述的行为被删掉了、代码并没有紧跟注释之后（因为有人在注释和原来的代码之间插入了新的代码）、注释和代码不一致，因为代码被修改了而注释却没有变化。

我觉得这种注释比不写注释还恶心，我憎恨注释。

Leahy 并没有完全否定注释的作用，但他只对 10,000 行代码写了一行注释：

有时注释还是很有用的，比如设计上有不可避免的约束（性能变化等）时就可以加上一些注释。我尽量不写注释，我们大概每 10,000+ 行代码会写一行注释（除了无聊的 xmldoc 注释，我个人觉得这种注释只对于 public API 有用，别的地方一无是处）。

Justin Rudd 说他得在目前所从事的项目中写大量注释，因为里面的 API 实在是“太糟糕了”：

目前我正为 Visual Studio 编写一个源代码控制包。API 实在是太糟糕，没办法只能多写注释了，这样我就能想起来为什么在一个地方需要传递 Guid.Empty 而在另一个地方（看起来很相似的地方）需要传递一个特殊的 GUID，否则一切就都乱套了。

我对实现的 4 个解决方案事件接口加了注释，这样后面的人即便是看到 7 个方法中有 6 个似乎没用也不会把他们删掉了。

我对方法为何要返回一个特定的 HRESULT 加了注释，因为如果返回 S_OK 的话 Visual Studio 会崩溃（Connect 中是这么说的）。

虽然文档说可以传递 null，但你不能这么做，我在这个地方加了注释。

在这个项目中，代码与注释的比例为 2：1。

Chris Tavares 使用注释来标明 bug 被修复了：

注释”// doing this because it fixes bug #####“并不是一种坏味道——事实上这是必要的。

然而 Brandon Molina 认为在代码中通过注释来标明修复的 bug 并不好，使用版本控制系统才是上策：

如果修复了 10 个 bug 该怎么办呢？代码将充斥着大量无用的信息。在这种情况下应该使用版本控制。注释加上 diff 才是明智之举。

Brad Wilson 补充了一条原则以避免差劲的注释：

“Why”注释 == good

“How”注释 == suspect

Timo Hilden 写了一篇关于代码注释的文章，他坚持认为好的注释是非常有必要的：

不理会代码注释很容易，但还是让我们面对它吧。作为程序员，我们不指望获得普利策奖（普利策奖是由美国颁发的一个奖项，主要用于奖励那些在新闻报道、文学创作以及音乐创作方面有杰出贡献的人，该奖项由美籍匈牙利人约瑟夫 普利策创建，现在由位于纽约的哥伦比亚大学负责——译者注），因此写不写注释与表达能力强不强没有什么关系，这仅仅事关懒惰与否。

坦白地说，更糟糕的是在代码需要注释的时候却没有编写。首先，这间接地说明了程序员缺少对同伴的尊重。每个人都知道查看大量的类是多么不爽的一件事，尤其是其中包含很多含义模糊、自我描述性差的函数，更有甚至，之前编写代码的人度假去了、离职了或是由于其他原因找不到了。程序员应该是个艺术家而同伴则是其观众。作为艺术家，应该尊重我们的观众。

其次，不写注释表明程序员太过于自负了。当然了，在写代码的时候我们很清楚自己在干什么，编程的时候脑子里会有很多想法，但下一次再看自己所编写的代码时将很可能无法找回当初的想法。以上这些都是常事，这需要我们在适当的地方编写具有描述力的注释。

Hilden 并不赞同取消文档（几年前由Scott Swigart和Jeff Atwood提出的观点）的做法，看看下面这个过度注释的代码片段：

// Declare category id for products
const int prodCategoryId = 1024;

// Create an iterator over products
vector<Product>::iterator iter = products_.begin();

// Iterate through all products
for ( ; iter != products_.end(); ++iter )
{
    // Assign categody id to each product
    iter->AssignCategoryId( prodCategoryId );
}

他建议将上面这些注释合并成一行用于说明代码的总体意图而非每行的意思：

// Assign categody id to each product
const int prodCategoryId = 1024;
vector<Product>::iterator iter = products_.begin();

for ( ; iter != products_.end(); ++iter )
{
    iter->AssignCategoryId( prodCategoryId );
}

各位读者，你采取何种手段编写注释呢？这些方法是公司的硬性规定还是自己选择的呢？你支持“编写尽可能少的注释”这种观点么？是否相信后继者能理解你所编写的代码么？你认为程序员是否需要花时间对代码中那些不太好理解的地方加注释么？

查看英文原文：To Comment or Not to Comment

架构语言 & 开发文化 & 方法