【转】注释的13条技巧

 作者:José M. Aguilar(西班牙语)

英文译者:Timm Martin

中文译者:numenzq

 

下面的13个技巧向你展示如何添加代码注释,这些技巧都很容易理解和记忆。

1. 逐层注释
为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:
针对每个类:包括摘要信息、作者信息、以及最近修改日期等
针对每个方法:包括用途、功能、参数和返回值等
在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推动注释工作完成得更好。
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艺术,搞笑,诗情画意,hyperverbosity的注释。简而言之,保持注释简单直接。

7. 使用一致的注释风格
一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何,Successful Strategies for Commenting Code已经规定和阐述了注释的一致性和针对的读者。就个人而言,我怀疑大部分非编程人员将会去阅读代码,因此注释应该是针对其他的开发者而言。

8. 使用特有的标签
在一个团队工作中工作时,为了便于与其它程序员沟通,应该采用一致的标签集进行注释。例如,在很多团队中用TODO标签表示该代码段还需要额外的工作。

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

注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。

9. 在代码时添加注释
在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该write comments before 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大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。

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里讲解得相当好),确保正确的缩进,并且采用coding style guides,违背这个技巧可能的结果就像是注释在为不好的代码apologize。

13. 与同事分享技巧
虽然技巧10已经向我们表明了我们是如何从好的注释中直接受益,这些技巧将让所有开发者受益,特别是团队中一起工作的同事。因此,为了编写出更容易理解和维护的代码,尝试自由的和你的同事分享这些注释技巧。
   







======================================================================================================================
介绍你一个小知识吧(说是小知识,不过关系重大)
就是如何写注释.以往我一直都比较困惑注释到底要写些什么,常常注释了很多,可是回头看的时候却发现注释一点信息量也没有

一般我们所说的注释都是针对函数(也就是方法),因为函数是模块化设计的最小单元(类还不算最小单元)
一个函数意味着一个功能,所以,函数的注释至少要有两条:
1.这个函数在什么情况下可以得到正确的运行结果,比如开平方的函数,参数不能为负数.
  这个叫做'前导条件',建议在方法的开头注明,像这样 :
void xxx() {
   //pre : 前导条件
}
  不是所有的函数都具有前导,有的函数可以在任何情况下得到正确结果,比如加法之类的.
  所以,有时候,前导条件可以省略不写
2.这个函数执行之后会造成什么影响.比如设置对象的某个状态或者返回某一个值.
  这个叫做'后置条件',建议在方法的结尾注明,像这样 :
void xxx() {
  ....
  //post : 后置条件
}
  所有的函数都具有后置条件.因为一个函数被调用之后肯定会造成影响,否则这个函数就没有存在地意义.
  一定要写明每一个函数的后置条件.
3.函数当中如果用到了公式或者定理,要在注释当中用了那条定理或者公式,最好能付上公式或者定理的简要说明.(当然,如果是勾股定理这种简单的,不说也可以)
4.如果某一段代码是顺序不能颠倒的,要注明,像这样:
   ...;
   #隔一行
   //处理XXX
   //sequence dependent
   //1st : xxx
   ....;
   //2nd : xxx
   ...;
   //3rd : xxx
   ...;
   #隔一行
   .....

注意了这几点,应该就不会再遇到不知道该注释什么,或者注释中尽是废话(我常常这样) 的问题了.

注意 : 在写代码的时候写的注释才有价值,如果在代码已经写完才来补注释,那么就不要再补了,把要写的写进文档就可以.
注释要求记录程序员写程序时候的思维过程

这里提到的只是我个人的编码习惯,主要是介绍一下写注释需要注意的一些细节.

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值