注释还是不注释【中英文对照版】

Any developer has written at least one line of comment throughout his code. Some have written many comments in an attempt their code to be more explanatory. This article gathers some of the practices used in writing code comments.

每个开发者都至少在代码中写过一行注释，一些人为了解释代码写了很多注释。本文收集了一些编写代码注释的实践。

The members of the Seattle Area Alt.Net group have discussed the need and practices for writing code comments. Kelly Leahy prefers self-explanatory written code with very few comments interspersed because he believes comments “only introduce incorrect noise into the system” since they tend to “get left behind in the dust when making code changes”:

Seattle Area Alt.Net项目组针对写注释的事情进行了讨论。Kelly Leahy倾向于编写自说明性质的代码以及少量的注释。他认为“注释只是说明了系统中不正确的地方”并且他注意到“修改代码的时候经常会忘记了同时修改注释”

[writing comments] it's a personal thing for most people, but I tend to lean very strongly against comments because of their propensity to get left behind in the dust when making code changes - I've seen it happen TOO many times where some comment refers to code that no longer exists, behavior that no longer exists, code that isn't immediately after the comment (because
someone inserted a new line of code between the comments and the original code) or says something that simply isn't true anymore, just because the code got changed and the comment was left alone.

[编写注释]编写注释很大程度是依赖于个人习惯。我倾向于写一些简单明了的注释，而不是那种经常会被忘记同步更新的注释。我见过太多这种的情况:代码都已经不存在了，但是注释还在。代码没有紧挨着注释，可能是某个人在代码和注释之前写了新的代码。或者注释本身就是不正确的，因为代码已经被修改了，但是注释没有。

I find those comments to be so much worse than the lack of comments that I abhor comments altogether.

我发现注释太多还不如没有注释，我讨厌大段大段的注释。

Leahy does not exclude comments entirely and he is using one line of comment for about 10,000 lines of code:

Leahy排斥注释，所以他的10000行代码中可能只有1行注释。

comments can sometimes be useful when you have constraints on design that can't be avoided (performance changes, etc.) that might require a bit more explanation.  I still try very hard to avoid them, and we probably have 1 comment line for every 10000 or more lines of code (except for the silly xmldoc comments, which I personally think are useless noise except in public API work).

如果你的设计当中存在约束条件（比如性能）的时候，注释有时也会非常有用的，而且这种情况也是难以避免的，因为你需要针对约束做一些说明。这种的情况下我也无法避免，所以我们很可能每10000行代码才会有1行注释。（除非是xmldoc注释，对于我个人而言的话，只要公开的API才有写注释的必要，否则那只会是没用的噪音）

Justin Rudd explained that he needed to use many comments in his current project because its API “is so messed up”:

Justin Rudd介绍说他的现在项目需要些很多的注释，因为项目中的那些API太混乱了：

Right now I'm writing a source control package for Visual Studio.  That API is so messed up that I have to comment what I'm doing so I remember why in one place I pass Guid.Empty and in  another (seemingly similar) that I have to pass a particular GUID or it blows up.

我现在正在写一个Visual Studio的源代码管理组件。那些API是在是太混乱了，以至于我不得不在代码中增加注释，这样我会记得这个地方为什么要传递Guid.Empty，而另一个看来类似的地方却要传递一个特殊的GUID。否则，你就会搞砸了。

I comment which of the 4 solution event interfaces I'm implementing so that the next person that comes along and sees 6 of the 7 methods seemly stubbed out won't delete them.

在现在的解决方案中，我为正在开发的4个事件接口添加了注释，希望下一个开发者不要删除7个函数中的那6个。

I comment why I am returning a particular HRESULT out of a method because when I return S_OK - Visual Studio crashes (and it is documented in Connect).

我会注释为什么某一个函数需要返回HRESULT，而不是返回S_OK。返回S_OK的时候，Visual Studio Crash了。（在关联的地方，这类的事情会被注释）

And I comment that even though the docs say you can pass null, you really can't.

我还注释那些文档中说你可以传递null的地方，事实上却不可以。

In this project, I probably have a 2 to 1 code to comment ratio.

在这个项目中，代码和注释的比例可能有2：1。

Chris Tavares uses comments for bug fixes:

Chris Tavares用注释来标记解决Bug：

The comment "// doing this because it fixes bug #####" is not a smell – in fact it's essential.

事实上，这类注释“//这么做是为了解决什么bug”不是坏味道，而是必须的。

But Brandon Molina believes it is better to comment bug fixes using the version control system rather than doing it inside the code:

但是Brandon Molina认为修改Bug的注释最好可以记录在版本控制系统中，而不是在代码内：

What happens when 10 bug fixes are made?  The code is current and now you have a paragraph of useless information cluttering your code.  Use version control for this.  Where a comment is combined with a diff and the comment actually has useful context.

这样修改10个Bug之后会怎样呢？你可能有一大段没用的注释，这会让你的代码看来更加混乱。还是使用版本控制系统吧。这样在你对比代码是，结合上下文的意思，注释会变得非常有用。

Brad Wilson added a guiding rule to avoid smelling comments:

Brad Wilson提出了一个添加注释的原则：

"Why" comments == good
"How" comments == suspect

“为什么”型注释 == 好注释

“怎样实现”型注释 == 不好的注释

Writing on code comments, Timo Hilden insisted on the need to include good comments:

在code comments上，Timothy Hilden坚持需要一些好的注释：

It’s easy to disregard writing code comments. Let’s face it, we as coders are not going for the Pulitzer Prize, so it’s not about the lack of personal ability of being able to express oneself, it’s just plain laziness.

不写注释是很容易的。说实话吧，我们这些开发人员又不是为了获取普利策奖，这不是表现个人能力，这只是关乎是否懒的问题。

To be honest, leaving code without descriptive comments where they’re needed is much worse than that. Firstly, it indirectly shows the programmer’s lack of respect towards his peers. Everyone knows how frustrating it is to wade through dozens of classes and even more functions with cryptic, non-self-descripting code, especially when the original coder is on vacation, has left the company or otherwise not unavailable for any other reason. A programmer is an artist, with fellow programmers as the audience. And as all artists, we should learn to respect our audience.

说实话，当代码需要注释而没有注释的时候，那会更糟糕。首先，这是对同事的一种不尊重。每个人都知道，当原作者在度假，或者离职，或者是其他原因导致原作者无法提供帮助的时候，需要去看那些含糊不清的，无法自说明的类和方法，会有多么地沮丧。程序员就像文章的作者，而后面的程序员就像是读者。就像作者一样，我们应该学会尊重我们的读者。

Secondly, leaving out comments shows the programmer’s overconfident attitude towards himself. Sure enough, when writing code, we usually have a good idea of what we’re doing. But programming is often about juggling several things in mind at once, and when you next time look at your code, it may be quite difficult to get back to the mindset you were in when writing the code originally. In these quite common situations, it pays to have descriptive comments in place.

其次，不写注释的程序员对于自己过于自信。毫无疑问，我们在写代码的时候总是很有思路。但是在编程时，我们总是要同时考虑好几件事情。当你下次回过头再来看这些代码的时候，你很难回想起当时编写代码的思路。这种情况下，就应该在某个地方添加注释了。

Hilden does not support undocumenting – a practice mentioned by Scott Swigart and Jeff Atwood years ago -, considering the following example as excessive commenting:

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 );

}

He suggested combining all the above comments into one explaining the general idea not every step made:

他建议将所有的这些代码合并到一行，而不是注释每一步代码：

// Assign categody id to each product

const int prodCategoryId = 1024;

vector<Product>::iterator iter = products_.begin();

 

for ( ; iter != products_.end(); ++iter )

{

    iter->AssignCategoryId( prodCategoryId );

}

What practices for writing comments are you using? Are there practices enforced by your company or chosen on your own? Are you supporting the writing-as-few-as-possible-comments policy, believing that the next develop will understand your code, or do you think one should take the time documenting what it is not so obvious?

您编写注释的习惯是什么？这些习惯是公司强制要求的，还是你自己选择的？你是否支持那种尽可能少的注释政策，相信下一个开发者会理解你的代码，还是认为你应该花一些时间来注释那些不太清晰的代码。

 

【原文链接：http://www.infoq.com/news/2010/03/To-Comment-or-Not-to-Comment】