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

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

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

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

赞 (0)

相关推荐

  • 编写高效jQuery代码的4个原则和5个技巧

    jQuery的编写原则: 一.不要过度使用jQuery 1. jQuery速度再快,也无法与原生的javascript方法相比,而且建立的jQuery对象包含的信息量很庞大.所以有原生方法可以使用的场合,尽量避免使用jQuery. 复制代码 代码如下: $("a").click(function(){    alert($(this).attr("id"));});//改良后↓$("a").click(function(){    alert(t

  • PHP代码优化技巧小结

    PHP代码优化技巧小结

    PHP优化的目的是花最少的代价换来最快的运行速度与最容易维护的代码.给大家提供下面这些优化技巧: 1. echo 比 print 快. 2. 使用echo的多重参数代替字符串连接. 3. 在执行for循环之前确定最大循环数,不要每循环一次都计算最大值,最好运用foreach代替. 4. 对global变量,应该用完就unset()掉. 5. 用单引号代替双引号来包含字符串,这样做会更快一些.因为PHP会在双引号包围的字符串中搜寻变量,单引号则不会. 6. 函数代替正则表达式完成相同功能. 7.

  • JavaScript避免代码的重复执行经验技巧分享

    我喜欢到一些大型网站上去翻阅它们的原代码,期望能找到一些可以应用到自己的代码中的模式,或发现一些之前从未听说过的工具和技巧.可是,在我查看这些大型网站的源代码时,经常会发现一个问题,那就是重复的代码执行,重复的功能应用.下面就是一些在查看它们的源代码时发现一些问题,把这些分享给大家,希望能让你们更加简洁高效的写出JavaScript代码. 重复的收集元素 我在他们的JavaScript代码里看到的最常见的问题是重复的收集元素.虽然jQuery选择器引擎或querySelectorAll的执行速度

  • css代码优化的12个技巧

    1.ID 规则2.Class 规则3.标签规则4.通用规则对效率的普遍认识是从Steve Souders在2009年出版的<高性能网站建设进阶指南>开始,虽然该书中罗列的更加详细,但你也可以在这里查看完整的引用列表,也可以在谷歌的<高效CSS选择器的最佳实践>中查看更多的细节.本文我想分享一些我在编写高性能CSS中用到的简单例子和指南.这些都是受到MDN 编写的高效CSS指南的启发,并遵循类似的格式. 一.避免过度约束 一条普遍规则,不要添加不必要的约束. 复制代码 代码如下: /

  • 高质量PHP代码的50个实用技巧必备（下）

    接着上篇<高质量PHP代码的50个实用技巧必备(上)>继续研究. 26. 避免直接写SQL, 抽象之 不厌其烦的写了太多如下的语句: <span style="color:#333333;font-family:''Helvetica, Arial, sans-serif'';">$query = "INSERT INTO users(name , email , address , phone) VALUES('$name' , '$email' ,

  • 优化PHP代码技巧的小结

    优化PHP代码技巧的小结1. 如果一个方法能被静态,那就声明他为静态的,速度可提高 1/4;2. echo 的效率高于 print,因为 echo 没有返回值,print 返回一个整型;3. 在循环之前设置循环的最大次数,而非在在循环中;4. 销毁变量去释放内存,特别是大的数组;5. 避免使用像__get, __set, __autoload 等魔术方法;6. requiere_once()比较耗资源;7. 在 includes 和 requires 中使用绝对路径,这样在分析路径花的时间更少;

  • 高质量PHP代码的50个实用技巧必备（上）

    50个高质量PHP代码的实用技巧,希望大家喜欢. 1.不要使用相对路径 常常会看到: require_once('../../lib/some_class.php'); 该方法有很多缺点: 它首先查找指定的php包含路径, 然后查找当前目录.因此会检查过多路径.如果该脚本被另一目录的脚本包含, 它的基本目录变成了另一脚本所在的目录. 另一问题, 当定时任务运行该脚本, 它的上级目录可能就不是工作目录了.因此最佳选择是使用绝对路径: view sourceprint? define('ROOT'

  • WordPress开发中短代码的实现及相关函数使用技巧

    其实实现短代码很简单,我们只需要用到 WordPress 里面的一个函数就可以搞定短代码,外加自己的一个小函数,可以让短代码实现的轻松加愉快. 短代码实现原理 就像往 WP 一些动作里加钩子和过滤函数一样, 短代码只是经过封装了的针对文章输出内容的过滤器而已, 没有像有一些主题功能说的那么震撼.那么高深. 下面来一个简单例子: function myName() {//短代码要处理的函数 return "My name's XiangZi !"; } //挂载短代码 //xz为短代码名

  • 让代码整洁、过程清晰的BASH Shell编程技巧

    这是我写BASH程序的招式.这里本没有什么新的内容,但是从我的经验来看,人们爱滥用BASH.他们忽略了计算机科学,而从他们的程序中创造的是"大泥球"(译注:指架构不清晰的软件系统). 在此我告诉你方法,以保护你的程序免于障碍,并保持代码的整洁. 一.不可改变的全局变量 1.尽量少用全局变量 2.以大写命名 3.只读声明 4.用全局变量来代替隐晦的$0,$1等 在我的程序中常使用的全局变量: 复制代码 代码如下: readonly PROGNAME=$(basename $0) read

  • 60个很实用的jQuery代码开发技巧收集

    60个很实用的jQuery代码开发技巧收集

    由于内容比较多建议用CTRL+F搜索 偶然在网上看到这些不错的jQuery代码开发技巧.原文收集了30个,另外查找的时候发现了还有20个.加上另外十个实用的jQuery代码片段,共60个代码技巧,收集在一起分享给大家. 1. 创建一个嵌套的过滤器 .filter(":not(:has(.selected))") //去掉所有不包含class为.selected的元素 2. 重用你的元素查询 var allItems = $("div.item"); var keep

  • 30个经典的jQuery代码开发技巧

    本文实例总结了30个经典的jQuery代码开发技巧.分享给大家供大家参考.具体如下: 1. 创建一个嵌套的过滤器 复制代码 代码如下: .filter(":not(:has(.selected))") //去掉所有不包含class为.selected的元素 2. 重用你的元素查询 复制代码 代码如下: var allItems = $("div.item"); var keepList = $("div#container1 div.item")

  • Ruby的25个编程细节（技巧、实用代码段）

    1.try 永远不会抛出异常 在 没有的时候 返回 nil 复制代码 代码如下: province_id = Province.find_by_name(prov).try(:id) 2.find(:first, :condotions) 方法 不言而与 复制代码 代码如下: mobile_info = MobileInfo.find(:first, :conditions => ["mobile_num = ? ", mobile_num.to_i]) 3.find(:all,

随机推荐