[翻译]13 Tips to Comment Your Code

 

13 Tips to Comment Your Code

1.Comment each level

对每一级用统一的方法注释每个代码块，例如：

n         为每个类，包含简短的描述，作者和最后修改日期

n         为每个方法，包含其目的，功能，参数，返回值

团队编程时，采用标准的注释是很重要的。当然，采用代码协定和工具（比如c#中的XML和java中的Javadoc）帮助这项工作也是可接受的，甚至更可取。

2.Use paragraph comments

       将代码块分成多个片段，每个片段执行一个简单的任务，然后在每个片段前添加注释，引导读者即将发生什么。

// Check that all data records
// are correct
foreach (Record record in records)
{
    if (rec.checkStatus()==Status.OK)
    {
        . . .
    }
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3.Align comments in consecutive lines

       对于多行且每行后都紧跟着注释的情况，我们应该排列这些注释，使它们更易读懂。

const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F;    // mask bit TCP

      一些开发人员用Tab来排列注释，其他的则用空格。最佳途径还是用空格，因为在各种编辑器和IDE中，tab键的行为多种多样。

4.Don’t insult the reader’s intelligence

    避免显然的注释，比如：

    if (a == 5)      // if a equals 5
        counter = 0; // set the counter to zero

      这既浪费时间写不必要的注释，又使读者分心，因为这些细节读者很容易从你的代码中推断出来。

5.Be polite

    避免粗鲁的注释，比如“Notice the stupid user has entered a negative number,”或“This fixes the side effect produced by the pathetically inept implementation of the initial developer”。此类注释很难在他们的程序代码中得到好的效果，并且你甚至不知道以后谁会读这种注释，你的上司，客户或可怜的愚蠢的新手。

6.Get to the point

    不要写无关你要传达意思的注释。避免笑话，诗歌和赘言。简而言之，保持注释简洁，直接。

7.Use a consistent style

    一些人认为注释应该写的让非程序员也能明白，其他人则认为只对程序员即可。无论如何，作为成功的代码注释策略，应该是一致的以及总是面向相同的读者。个人意见，我甚至怀疑很多非程序员是否会读代码，所以注释应面向程序员。

8.Use special tags for internal use

    团队开发时，采用一致的一套标签作为程序员间的沟通。比如，很多团队使用“TODO:”标签来指出需要附加编写的代码段：

int Estimate(int x, int y)
{
    // TODO: implement the calculations
    return 0;
}

标签注释并不解释代码，它们往往寻求注意或传递信息。但是，如果你用这种方法，务必将你要传递的信息写上。

9.Comment code while writing it

    在 编写代码是添加注释，此时它们在你脑中还是清晰的。如果你直到最后才来添加，将事倍功半。“I have no time to comment“，”I’m in a hurry”和“the project is delayed”都是简单的借口而阻止代码中写文档。一些开发人员认为你应该在编写代码前写注释作为一种筹划最终方案的途径。举例：

public void ProcessOrder() 
{
    // Make sure the products are available
    // Check that the customer is valid
    // Send the order to the store
    // Generate bill
}

10.Write comments as if they were for you(in fact,they are)

    注释代码时，不仅仅要考虑其他开发人员以后可能会维护你的代码，也要考虑你自己。

伟大的Phil Haack曾说过："As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code."

    结果，我们自己将是优良（笨拙）注释的第一个受益（害）者。

11.Update comments when you update the code

      如果注释没有随着代码更新，那样的注释不能保证正确。代码和注释必须同步修改，否则你的注释将使维护你代码的开发人员的工作很难做。特别要注意重构工具自动的更新了你的代码而没有改变你的注释的情况，这也将导致同样的结果。

12.The golden role of comment:readable code

      程序员的基本功之一：让你的代码为自己说话。尽管一些不喜欢写注释的人怀疑这是程序员们瞎编乱造的，不过事实是自明的代码对于编写更易懂的代码甚至使注释变的不必要有很好的帮助。例如，在我的Fluid Interfaces文章中展示了干净自明的代码可能是这样的：

Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

    在这个例子里，注释是不需要的而且那样做可能会与第4条相违背。为了写出更易读的代码，你可能要考虑使用合适的命名方式（Stringer’s Rules）,确保正确的缩排和采用代码样式指南。不遵守这条提示的结果可能是注释看起来象似向糟糕的代码道歉。

13.Share these tips with your colleagues

    尽管我们在第10条中指出我们自己是怎样立即从优良的注释的受益的，但是这些条款对所有开发人员都有用，尤其是团队开发。因此，请将这些注释条款与你的同事分享，一起写易懂和易维护的代码。