分类:
2011-01-24 14:22:12
http://numenzq.javaeye.com/blog/177079
关键字: documentation, comment, tips作者:José M. Aguilar(西班牙语)
英文译者:Timm Martin
中文译者:numenzq
下面的13个技巧向你展示如何添加代码注释,这些技巧都很容易理解和记忆。
如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下:
// Check that all data records如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
在分隔代码和注释时,有的开发者使用tab键,而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致,因此最好的方法还是使用空格键。
避免以下显而易见的注释:
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。
避免粗鲁的注释,如:“注意,愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣,你也永远不知道谁将会阅读这些注释,可能是:你的老板,客户,或者是你刚才侮辱过的无能开发者。
不要写过多的需要转意且不易理解的注释。避免ASCII艺术,搞笑,诗情画意,的注释。简而言之,保持注释简单直接。
一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何,已经规定和阐述了注释的一致性和针对的读者。就个人而言,我怀疑大部分非编程人员将会去阅读代码,因此注释应该是针对其他的开发者而言。
int Estimate(int x, int y)
{
// TODO: implement the calculations
return 0;
}
注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。
在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该,用于理清头绪。例如:
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。
对于开发者的一个基本原则就是:让你的代码为己解释。虽然有些人怀疑这会让那些不愿意写注释的开发者钻空子,不过这样的代码真的会使你容易理解,还不需要额外维护注释。例如在文章里向你展示的代码一样:
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
在这个例子中,注释是不需要的,否则可能就违反了技巧4。为了使代码更容易理解,你可以考虑使用适当的名字(里讲解得相当好),确保正确的缩进,并且采用,违背这个技巧可能的结果就像是注释在为不好的代码apologize。
虽然技巧10已经向我们表明了我们是如何从好的注释中直接受益,这些技巧将让所有开发者受益,特别是团队中一起工作的同事。因此,为了编写出更容易理解和维护的代码,尝试自由的和你的同事分享这些注释技巧。
同类型的文章有: