[译林系列-软件工程]13 TIPS to comment your code

声明：这篇文章的原文出自José M. Aguilar的Variable Not Found，这里仅对其进行中文转译工作，一切版权归原作者所有

以下将会介绍13给有用的TIPS供你参考注释代码，借此你可以很容易的维护理解你的代码：

1、分级注释

对于每一个代码块,每一级代码都进行统一风格的注释，例如：

=>对于每一个class，注释应该包含简介，作者，和最后修改日期

=>对于每一个方法，注释应该包含方法的目的，功能，参数，返回值的简介

团队工作中统一风格的注释显得格外重要。当然，我们能够接受也推荐使用代码注释工具（例如xml in c#或者javadoc for java)来简化这项任务。

2、段注释

我们可以用注释来将代码块分解成多个“段”，每一个段完成一个单一的任务。段注释将会在段起始处说明段内代码的功能，使阅读者明确接下去代码的功能。

// 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、对齐的连行注释

对于多行连续代码的尾部注释，将注释对齐将会方便阅读者的阅读

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

一些程序员习惯用tab来对齐注释，然而其他人却喜欢用空格。因为tab的占位是取决于不同IDE的，而空格则没有这个问题，因此最佳的方法是使用空格。

4、不要侮辱读者的智慧

要避免对功能显而易见的代码进行注释，比如：

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

这不仅浪费你的时间去写这些毫无意义的东西，而且这些显然能从代码中推断出的“细节”还扰乱了读者的思路。

5、请礼貌些~

避免粗鲁的注解，比如“那些愚蠢的家伙输入了个负数”或者“这修正了那些可悲又愚蠢的程序员最初实现的副作用”。这些注释将给作者带来不必要的麻烦，你根本不知道将来谁会来阅读你的代码：你的老板，你的客户，或者是那些你刚侮辱的“可悲”程序员。

6、一针见血

请不要写过多的废话来表达你的思想。要避免使用ASCII ART，笑话，诗歌，hyperverbosity（译者注：天哪，谁会去写这些诡异的东西？）。总而言之，保持你注释的简单，明了。

7、统一的风格

一些人认为注释的一种作用是让非程序员来读懂代码。而另一些人认为注释仅仅是服务于程序员的。在任何情况下，正犹如Successful Strategies for Commenting Code中所说，最终要的是注释风格要连贯 ，并且面向统一的阅读者。就我个人而言，我很怀疑那些非程序员会去阅读我们的代码，因此注释应该服务于程序员。

8、为团队服务的特殊标记

当我们团队协作时， 常会用一些特殊的标记来交流。比如，很多团队用"TODO:"标记来说明这段代码需要补充额外的工作：

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

这些标记并非用来解释代码，而是作为讯息发布的工具。但是，请记住这一点，当你利用这些标记工作时，请确切地理解标记的含义，并且去完成标记隐含的需要你做的工作。

9、边CODE边注释

在编写代码的同时完成注释，这有助于你时刻了解自己在干什么。如果你把这项工作放到最后，你不得不痛苦地做第二次的“编码”工作。“我没有时间写注释”，“我很忙”，“项目进度已经晚了”都是我们常用的理由来搪塞注释的编写工作。一些程序员认为应该在CODE前就开始注释的编写，这有助于对程序有一个总体的计划。例如：

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

10、为自己而写

当写代码时，请好好考虑，你不单单是为那些将来维护你代码的程序员写注释，同时也是为你自己。用伟大的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、更新代码的同时更新注释

如果代码并没有改变，那么注释也就没有必要进行修改。但是代码与注释是一体的，两者要保持同步的更新，否则维护者将会发现读懂你的代码是一项极其痛苦的工作。这里要注意那些重构工具，它们常常为你更新了代码却留下了一堆不知所谓的注释。

12、黄金准则：可阅读的代码

一条程序员的基本准则是：让你的代码自己解释自己。虽然有人质疑那些不愿意写代码的程序员提出这项原则的动机，但那些可自解释的代码的的确确能够很好的解释程序，并且使得注释毫无用武之地。比如，在我的Fluid Interfaces 这篇文章中表现了自解释代码是多么地清晰易懂：

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

在这个例子中，注释是没有必要的并且是有悖于TIP 4的。为了写出可阅读的代码，你应该要使用那些合适的变量名，保证正确的缩进，以及采用编码样式指导（coding style guides）。如果没能做到这一点，你就不得不为你那些糟糕的代码负责了~

13、与你的同事分享这些TIPS

虽然TIP 10说明了我们自己能够从优秀的注释中获益良多，这些TIPS同样有益于你的同事们，特别是与自己一同工作的团队成员。因此，和你的同事们自由得分享这些TIPS， 你会发觉代码是多么得容易编写与维护。