编写可读代码的艺术 （6）

第六章 写出言简意赅的注释

上一章主要介绍了要在哪些地方写注释，这一章着重介绍下如何写出言简意赅的注释。

在添加注释时，尤其需要注意的一点就是，注释应该有很高的信息/空间率。应该尽量把它写的精确细致，由于注释也会占用屏幕空间，所以注释也要努力写地很紧凑。

1、让注释保持紧凑

先看下一个典型C++类型的注释：

//the int is the CategoryType
//the first float in the inner pair is the 'score'
//the second is the 'weight'
typedef hash_map<int, pair<float, float>> ScoreMap;

和第二个版本的注释：

//CategoryType -> (score, weight)
typedef hash_map<int, pair<float, float>> ScoreMap;

明显第二段代码的注释更简洁一些。

2、避免使用不明确的代词

就像为函数或是变量起名字一样，我们在写注释的时候，也要避免使用不明确的代词。

//insert the data into the cache, but check if it's too big first

当你一眼看到这个代码时，你是否能快速的说出这个it是指什么呢？是cache还是data呢？最好能够改进这个句子，来消除疑惑。

//if the data is small enough, insert it into the cache

3、润色粗糙的句子

很多情况下，让注释更精确的过程总是伴随着让注释更紧凑

#Dependint on whether we've already crawled this URL before, give it a different priority.

与以下注释相比时：

#Give higher priority to URLs we've never crawled before。

第二个注释更紧凑，直接，通式还解释未曾爬到过的URL将得到更高的优先级，这在第一个注释里是没有体现的重要信息。

4、精确的描述函数的行为

有时候函数名仅仅描述了该函数的执行结果，并没有体现出该函数的具体执行标准。作为概括性注释，需要精确地描述函数的具体行为。

比如下列函数：

//return the number of lines in this file
int CountLines(string filenale) {...}

注释中提供的信息和函数中提供的信息一样多，它没有任何意义。我们需要在注释中提供更多的信息来描述这个函数的行为。统计行有很多标准，空白符号算1行还是0行？如果文件中有"hello world\n"、"hello\n world"，这样的语句算几行呢？最简单的实现方法是统计换行符‘\n’的个数（这个unix中wc命令的工作原理），相应的注释如下：

//count how many newline bytes('\n') are in the file

这段注释并没有比第一段长很多，但是它提供的信息却多了很多。

如果函数的逻辑比较复杂，过多的注释往往可能造成迷惑，这个时候最好能在注释中写一个特殊的输入输出例子作为参考，这样一眼就能看出输入参数和期望结果来，直观很多。

5、声明代码的意图

注释就是要告诉读者，你在编码时是怎么想的。看下面一段注释：

//Iterate through the list in reverse order.

这段注释可能只是描述函数的作用，更好的注释可能是这个样子的，//display each piece, from highest to lowest.第二段注释从更高的层次解释了这段代码要做什么，更符合程序员编码时的思维。

6、“具名函数参数”的注释

有时候我们可以在参数前后 添加注释让函数参数更加直观，比如：

connect(/*timeout=*/10, /*use_encryption=*/false);

这样的代码看上去是不是很直观，一目了然。

7、采用信息含量高的词

写注释也是一门功课，啰里啰嗦的注释会带来不好的印象，我们应该学会使用信息含量高的词来表达意思。可能你解释了一堆如何从flash读取数据，临时保存，如何使用临时值而不是频繁从flash读写，往往不如使用“缓存”一词，基本上每个程序员都会知道缓存的作用。