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艺术,写笑话,作诗和过于冗长。 简而言之就是保持注释的简单和直接。

7. 使用统一的风格

有些人觉得注释应该让非程序员也能看懂。 另外一些人觉得注释需要面对的读者只是程序员。 无论如何,正如Successful Strategies for Commenting Code中所说的,最重要的是注释的风格需要统一,并且总是面向相同的读者。 就自己而论,我怀疑非程序员是否会去读代码,所以我觉得注释应该面向程序员来写。

8. 在内部使用特殊的标签

当你在一个团队里工作的时候,采用一组一致的标签能帮助不同的程序员沟通。 例如,很多团队会采用“TODO”标签来表示一段尚未完成的代码

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

标签注释并不会解释代码,它们寻求注意或者是传递信息。 但是如果适当地使用这种技术,要记住跟进这段代码并且完成该标签传递的任务。

9. 在写代码的同时添加注释

当你在写代码而且记忆犹新的同时就添加注释。 如果等到项目后期才添加注释,会让你事倍功半。 “我没有时间写注释”,“我的时间很紧迫”和“项目已经延迟了”,这些都是不写注释的常见借口。 有些工程师觉最佳的解决方法是“注释先行”。

例如:

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曾经说过:

“一旦一行代码被敲到文件中, 你就已经要开始维护那一行代码了。”

所以,我们自己就是好(或者坏)注释的第一个受益者(或者受害者)。

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

在这个例子里面,注释就像是违反了第4条技巧那样,变得毫无必要。 要写出可读性好的代码,你需要使用适当的命名方式(在经典的Ottinger’s Rules中有阐述),保证恰当的缩进,并且采用编码风格指导。 如果代码不遵守这条技巧,那么注释看起来就好像是为自己不好的代码的写道歉信一样。

13. 跟你的同事分享这些技巧

虽然从第10条技巧中我们已经知道了自己就是好注释的得益者,但是这些技巧对于所有的开发者来说都是很有帮助的,尤其是整个团队都有相同共识的情况下。 因此,大方地跟你的同事去分享这些技巧,让我们写出更加容易理解和维护的代码。

继续阅读关于 的文章



Fork me on GitHub