技术头条 - 一个快速在微博传播文章的方式     搜索本站
您现在的位置首页 --> 编程语言 --> 如何进行更好的进行代码注释

如何进行更好的进行代码注释

浏览:2461次  出处信息

    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; // 数据包的最大数量
const MASK = 0x1F; // TCP标志位

    有些程序远使用制表符来进行对齐,有些则使用空格。建议使用空格来对齐,因为不同的代码编辑器对制表符的处理会不一样。

    4、不要侮辱读者的智商

    不要用这样的注释:

if (a == 5) // 如果a等于5
counter = 0; // 就将counter的值赋为0

    这样做只会浪费你的时间,而且读者的注意力会被从代码中转移。

    5、注意礼貌

    避免使用无礼的注释,如:注意有些蠢蛋会输入一个负数;这修复了程序最初版本遇到的问题,那个无个救药的笨蛋。这样的注释会反映作者的素质,而且你不知道将来谁会读到你的程序:你的老板、顾客,或者是你刚才辱骂过的那个程序员。

    6、讲重点

    不要在写冗余的注释,也不要用所谓的字符艺术、玩笑、小诗等。总之要保持注释的简单和直接。

    7、坚持统一风格

    有些人认为代码注释应该简单到让不会编程的人也能看懂,另一些人则认为代码注释只要让程序员看懂就可以了。不管怎样,正如《撰写代码注释的成功策略》中所提到的,代码注释的风格应该是固定的,是为同一个观众准备的。而且我个人认为不太会有非程序员来阅读代码,所以代码注释应该只是针对其他程序员的。

    8、使用内部统一规定的标签

    在进行团队开发时,可以在注释中使用一些特殊的标签。比如在一些团队中使用“TODO:“标签来表示这里还需要完成其他的一些任务。

int Estimate(int x, int y)
 {
 // TODO: 实现这项计算
 return 0;
 }

    这里所使用的标签注释并不是用来解释代码,而是引起读者注意并传递一些信息。如果你的团队确实在使用这类注释,就要保证会依此进行作业。

    9、边写代码边注释

    在写代码的时候,乘脑中记忆还清晰,及时写上注释。如果你想在程序编写完之后再添加注释,也许就会花费你两倍的时间。“我没有时间添加注释”、“我很忙”、“这个项目已经有所拖延了”都将会是你的借口。有些程序员认为你应该在编写代码之前就写好注释,以为你的最终方案作出计划。如:

public void ProcessOrder()
 {
 // 保证这些产品是可以购买得到的
 // 检查用户时候合法
 // 向商店发出订单
 // 生成账单
 }

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

    在这个例子中,代码不需要注释,否则会违反本文的第四条贴士。要写出可读的代码,你应该考虑使用恰当的名称(在Ottinger’s Rules中有所叙述),确保标识正确,并根据代码规范来撰写。如果没有遵循此条建议,注释可能会被看作是代码的一种“道歉”。

    13、和你的同事分享这些贴士

    虽然第10条贴士说我们自己将是代码注释的第一个受益者,但如果把这些贴士分享给你的同事,尤其是在同一个团队中工作的同事,你就会发现你们写出的代码注释会更为易懂和易于维护。

    参考地址:http://www.devtopics.com/13-tips-to-comment-your-code/

建议继续学习:

  1. 提高代码可读性的注释技巧    (阅读:6778)
  2. 注释里的诅咒:哪种语言遭受最多的咒骂?    (阅读:4501)
  3. 10个最“优秀”的代码注释    (阅读:3691)
  4. 一个实例:为什么注释是愚蠢的    (阅读:2372)
  5. 10个最“牛叉”的代码注释    (阅读:1491)
  6. 用 HTML 标记的古怪代码注释    (阅读:1431)
QQ技术交流群:445447336,欢迎加入!
扫一扫订阅我的微信号:IT技术博客大学习
后一篇:构造函数沉思录 >>
© 2009 - 2024 by blogread.cn 微博:@IT技术博客大学习

京ICP备15002552号-1