13个代码注释的小技巧

这篇文章是由José M. Aguilar在他卓越的博客中以西班牙语的形式首发，其后Timm Martin在获得Aguilar先生的授权下，对该文章进行翻译、修改，并且在DevTopics上发布。

以下13个小技巧可以使得你的代码在长时间内依然能够保持容易理解和维护。

1. 对不同级别的代码进行注释

对于不同级别的代码块，要使用统一的方法来进行注释。例如：

• 对于每一个类，需要包含一段简明扼要的描述，作者和上一次修改的时间

• 对于每一个方法，需要包含这个方法的用途，功能，参数以及返回结果

当你在一个团队里面的时候，采用一套注释的标准是非常重要的。当然，使用一种大家都认可的注释约定和工具（例如C#的XML注释和Java的Javadoc）在一定程度上能推动这项任务。

2. 使用段落注释

首先把代码块分解成多个“段落”，每一个段落都执行单一的任务；然后在每一个“段落”开始之前添加注释，告诉阅读代码的人接下来的这段代码是干什么用的

// 检查所有记录都是正确的
foreach (Record record in records)
{
    if (rec.checkStatus()==Status.OK)
    {
        . . .
    }
}
// 现在开始进行处理
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. 对齐注释行

对于那些在行末写有注释的代码，应该对齐注释行来使得方便阅读

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

有些开发人员使用tab来对齐注释，而另外一些人会用空格来对齐。由于tab在不同的编辑器和集成开发环境中会有所不同，所以最佳的方法是使用空格来对齐注释行。

4. 不要侮辱阅读者的智慧

要避免没用的注释，例如

if (a == 5)        //如果a等于5
    counter = 0    //把counte设为0

这不单把时间浪费在写没用的注释上面，同时也在分散读者的注意力。

5. 要有礼貌

应当避免没有礼貌的注释，例如“要注意一些愚蠢的用户会输入一个负数”，或者“修正由菜鸟工程师写的愚蠢得可怜的代码而导致的副作用”。这样的注释对于代码的写注释的人来说并没有任何好处，同时你永远都不会知道将来这些注释会被谁来阅读，你的老板，一个客户或者是刚才被你数落的愚蠢得可怜的工程师。

6. 直截了当

不要在注释里面写过多的废话。避免在注释里面卖弄ASCII艺术，写笑话，作诗和过于冗长。简而言之就是保持注释的简单和直接。