13个代码注释的小技巧
作者:maguschen 来源:译言 发布时间:2009-01-05 11:57:00
这篇文章是由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; // m
ask bit TCP
有些开发人员使用tab来对齐注释,而另外一些人会用空格来对齐。由于tab在不同的编辑器和集成开发环境中会有所不同,所以最佳的方法是使用空格来对齐注释行。
4. 不要侮辱阅读者的智慧
要避免没用的注释,例如
if (a == 5) //如果a等于5
counter = 0 //把
counte设为0
这不单把时间浪费在写没用的注释上面,同时也在分散读者的注意力。
5. 要有礼貌
应当避免没有礼貌的注释,例如“要注意一些愚蠢的用户会输入一个负数”,或者“修正由菜鸟工程师写的愚蠢得可怜的代码而导致的副作用”。这样的注释对于代码的写注释的人来说并没有任何好处,同时你永远都不会知道将来这些注释会被谁来阅读,你的老板,一个客户或者是刚才被你数落的愚蠢得可怜的工程师。
6. 直截了当
不要在注释里面写过多的废话。避免在注释里面卖弄ASCII艺术,写笑话,作诗和过于冗长。简而言之就是保持注释的简单和直接。
猜你喜欢
- 许多单位都已建立了局域网和广域网,并在网上运行业务处理程序。其实只要作一些简单配置就可以给公司员工提供新闻、信息浏览、传输文件、内部邮件、专
- SEO=∫Clock=∫C1+L2+K3+O41、∫是一个积分符号,C=content,L=
- 内容摘要:为了把损失降低到最低限度,我们一定要有安全观念,并掌握一定的安全防范措施,禁绝让黑客无任何机会可趁。下面我们就来研究一下那些黑客是
- 一个论坛社区如果要发展壮大,一个必要条件就是要有人气,形成自己独特的、有别于其他社区的特色或者文化,并有对新人产生潜移默化的影响。Discu
- SEO网站排名优化成为网络营销中不可忽视的力量,SEO成功制胜点在于链接。链接的初衷,目的很单纯,链接多半是为了用来介绍其它连接给访问者,所
- 尤其是对于那些公司规模更为庞大的系统管理员们来说,在Exchange2007的管理控制台上加强巩固“邮箱查看”功能,无疑是一个重大的胜利。创
- 下面就根据自己的经验介绍一点免费网络推广经验供大家参考。一、网络推广是用事实说话的我自从07年做了网上推广,发现和原来的传统营销有很大的区别
- 到底谁是真正的“开心网”?这个问题现在只能交由法律来最终裁定。昨日上午,北京市二中院开庭审理北京开心人信息技术有限公司(kaixin001.
- 11月7日消息,盛大游戏CEO李瑜今日在2009第二届WEBGAME与SNS社区运营大会上表示,目前的网页游戏行业出来了百家争鸣、百花齐放的
- Hyper-V Server 2008发布有一些时间了,想来,不少的虚拟化爱好者早已动手安装并在命令行下大展身手了,但对于广大的入门级爱好者
- Google日前推出了网站趋势(Google Trends For Websites)服务。这一新工具使用户能看到所有 网站的流量数据,并将
- 微软董事长比尔·盖茨(Bill Gates)将于本周五(6月27日,美国当地时间)正式退出公司日常管理工作,以把精力专注于慈善事业.在过去3
- 1、搜索引擎不友好搜索引擎对于难以处理和识别的打字稿、复数、连字号等等各种各样的问题,搜索的准确度会降低。显然,如果搜索引擎刻意
- 内容摘要:title标签对于提高你网站的排名起到非常重要的作用。尽管如此,有很多人对于怎样去构造一个合适的title还不是很清楚。以下是我对
- 在SEO过程中,域名与虚拟主机的选择有时也会起到一定作用,尤其是高手过招,胜负往往就在小细节上。选择域名和虚拟主机,是建站伊始就要实施的工作
- 一.分析选择关键词了解客户目标受众人群、受众率,推测有效的行业买家年龄段常用搜索习惯及搜索行为;选择精准产品关键词并骤一剖析筛选,确定最终预
- <?php $db_server = "localhost";$db_user = "TPAR
- 据GOS报道,Google在AdSense账户中提供了一种新的广告形式:AdSense for Feeds。早在今年5月份的时候Google
- 北京时间10月14日消息,据国外媒体报道,谷歌周二在一片博客文章中宣布,将大规模推广Google Voice电话软件的应用。在未来几个星期,
- 每一个“网络草根”,至少有10种方法,分别可以达到月赚3000。是的,月赚3000并没有什么,我现在也基本用不着这些方法,但对于某些有志之士