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

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

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