提高代码可读性的十大注释技巧分享

所属分类: 网络编程 / 相关技巧 阅读数: 229
收藏 0 赞 0 分享

本文讲述了提高代码可读性的十大注释技巧。分享给大家供大家参考,具体如下:

很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:

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大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。

更多精彩内容其他人还在看

图片的色彩空间问题

不知有多少朋友遇到此类问题:在PS里处理好的图,发到论论坛上以后发现图片颜色大变,变得灰蒙蒙,失去了层次,色彩生硬,还有点发青
收藏 0 赞 0 分享

计算机中的字符串编码、乱码、BOM等问题详解

这篇文章主要介绍了计算机中的字符串编码、乱码、BOM等问题详解,对文件编码、vim乱码、什么情况下会出现乱码、字符编码的发展历史、字符集和编码的区别、汉字ANSI编码的发展历史、BOM头等问题做了全面总结、详细介绍,需要的朋友可以参考下
收藏 0 赞 0 分享

markdown简介和语法介绍

这篇文章主要介绍了markdown简介和语法介绍,本文重点介绍了常用的一些markdown语法,可以做为一个简明版的入门指南,另本文还提供了一个在线学习markdown的简明教程,需要的朋友可以参考下
收藏 0 赞 0 分享

程序员开发项目是选择效率还是质量呢?

这篇文章主要介绍了程序员开发项目是选择效率还是质量呢?本文对这个每个程序员都会遇到的一个问题做了讲解,需要的朋友可以参考下
收藏 0 赞 0 分享

12种实现301网页重定向方法的代码实例(含Web编程语言和Web服务器)

这篇文章主要介绍了11种实现301网页重定向方法的代码实例,文中包含9种编程语言和3种WEB服务器配置方法,共计12种,需要的朋友可以参考下
收藏 0 赞 0 分享

命令行下的2款网页截图工具推荐

这篇文章主要介绍了命令行下的2款网页截图工具推荐,分别是针对IE浏览器的IECapt和针对Firefox浏览器的PageSaver,需要的朋友可以参考下
收藏 0 赞 0 分享

分享下程序员/设计师能用上的 75 份速查表

速查表可能是图片,也可能是 PDF 文件,希望你能在这个列表中找到你所需要的,
收藏 0 赞 0 分享

Geohash的原理、算法和具体应用探究

这篇文章主要介绍了Geohash的原理、算法和具体应用探究,Geohash可以实现当前手机应用中的查找附近的人功能,需要的朋友可以参考下
收藏 0 赞 0 分享

程序员编程从初级到中级的10个秘诀

在一封与TechRepublic会员交流的邮件当中,他提到了面向程序员的博客、文章及杂志分成两类:面向初学者类(“hello world”这种类型的教程)以及面向专家类(MSDN杂志)。
收藏 0 赞 0 分享

关于换行和回车的图文小结

不知道大家用这么多年的电脑,写了这么多的程序,对换行和回车有没有一个认识
收藏 0 赞 0 分享
查看更多