13个代码注释的小技巧(2)
作者:maguschen 来源:译言 发布时间:2009-01-05 11:57:00
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条技巧中我们已经知道了自己就是好注释的得益者,但是这些技巧对于所有的开发者来说都是很有帮助的,尤其是整个团队都有相同共识的情况下。因此,大方地跟你的同事去分享这些技巧,让我们写出更加容易理解和维护的代码。
猜你喜欢
- 今天早上,百度搜索引擎网站在中国很多地区都打开异常,疑遭类似黑客攻击,攻击者自称Iranian Cyber Army(伊朗网军)的组织篡改了
- 电脑报记者展开了长达一个月时间的深度调查,发现了一个惊人的事实:凭借自己的中文搜索上的绝对优势,百度已经成为一台庞大的敛财机器,更为可怕的是
- 导读:美国IT网站eWeek今天撰文称,虽然微软仍然在网络领域落后谷歌,但通过10大理由可以看出,微软仍然拥有很大潜力,并有望最终主导网络世
- 由于企业希望改进IT基础架构节省成本,所以CIO和数据中心管理人员都转向了通过合并服务器的方法以实现节省费用。其实,这么做并非易事。由于企业
- 一.首先进入Godaddy首页点Web Site Hosting,如下图然后在Deluxe Plan下选购买时间和所需操作系统(Linux或
- Immunet Project,赛门铁克公司响应中心前任总监奥利弗。弗雷德里希(Oliver Friedrichs)开发了一款基于云的免费杀
- 中国站长站(chinaz.com)据赛迪网-IT技术报道:昨天在调试一个博客系统时遇到了http500错误,于是按照2003时的解决方法在I
- 核心提示:SEO是一项相当复杂、精细的工作,成功的SEO涉及主动营销型网站建设从网站品牌的确立到ROI (Return on Investm
- 随着B/S模式应用开发的发展,使用这种模式编写应用程序的程序员也越来越多。但是由于这个行业的入门门槛不高,程序员的水平及经验也参差不齐,相当
- 与Windows XP相比,Windows Vista内置的桌面图标有了一定的变化,如移除了在Windows 系统中存在多年的IE(Inte
- 今天看了google的黑板报,传说中的谷歌中文手机语音搜索正式于二号发布,使用者可以通过自己的声音来和手机进行交互,找到自己所需要的信息。能
- 今天10月27来到公司,一大早的就听到到处都是嚷着我PR3了,我PR5了等......随手查了一下我前几天注册的几个域名,比如我的这个QQ头
- 虚拟服务器是有很多好处,但它的安全问题完全暴露了吗?如何确保安全性?可以采用下面十个积极步骤。去年,数据中心虚拟化方面的重大问题还是“该技术
- 第十七届万维网大会(WWW2008)结束招待晚宴在北京人民大会堂举行,昨晚,来自全球的互联网界精英悉数出席。百度总裁李彦宏在晚宴中致辞,并在
- 事实上,我们一直在谈论的SNS网站并非真正的SNS网站,这些以WebGame来聚拢人气的网站最多只能算是社区——游戏社区,还没有真正上升到S
- 北京时间11月13日消息,据国外媒体报道,谷歌旗下视频共享网站YouTube周四表示,从下周开始,该网站将支持1080p格式的全高清视频内容
- 老谢我也算得上是网站推广的老前辈了,一些网站推广经验和大家分享下。1.论坛推广这里所说的论坛推广绝对不是在论坛里一个一个版贴广告,也不是将网
- 今天需要实现一个功能,wordpress实现一篇较长的文章分页显示,于是乎找了很多资料,找了很久才找到,大部分都是3.0之前的实现方法,所以
- 一、安装POP3和SMTP服务组件Windows Server 2003默认情况下是没有安装POP3和SMTP服务组件的,因此我们要手工添加
- 确保您的网站被谷歌收录(并且出现在搜索结果页)使用site: 操作符 [site:example.com] 检查搜索结果中的内容摘要和页面标