Google C++编程风格指南（六）：代码注释

但不要有无谓冗余或显而易见的注释，下面的注释就没有必要加上“returns false otherwise”，因为已经暗含其中了：

// Returns true if the table cannot hold any more entries.

bool IsTableFull();

注释构造/析构函数时，记住，读代码的人知道构造/析构函数是什么，所以“destroys this object”这样的注释是没有意义的。说明构造函数对参数做了什么（例如，是否是指针的所有者）以及析构函数清理了什么，如果都是无关紧要的内容，直接省掉注释，析构函数前没有注释是很正常的。

函数定义：

每个函数定义时要以注释说明函数功能和实现要点，如使用的漂亮代码、实现的简要步骤、如此实现的理由、为什么前半部分要加锁而后半部分不需要。

不要从.***件或其他地方的函数声明处直接复制注释，简要说明函数功能是可以的，但重点要放在如何实现上。

5.变量注释（Variable Comments）

通常变量名本身足以很好说明变量用途，特定情况下，需要额外注释说明。

类数据成员：

每个类数据成员（也叫实例变量或成员变量）应注释说明用途，如果变量可以接受NULL或-1等警戒值（sentinel values），须说明之，如：

private:
// Keeps track of the total number of entries in the table.
// Used to ensure we do not go over the limit.-1 means
// that we don''t yet know how many entries the table has.
int num_total_entries_;

全局变量（常量）：

和数据成员相似，所有全局变量（常量）也应注释说明含义及用途，如：

// The total number of tests cases that we run through in this regression test.

const int kNumTestCases = 6;

6.实现注释（Implementation Comments）

对于实现代码中巧妙的、晦涩的、有趣的、重要的地方加以注释。

代码前注释：

出彩的或复杂的代码块前要加注释，如：

// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
x = (x << 8) + (*result)[i];
(*result)[i] = x >> 1;
x &= 1;
}

行注释：

比较隐晦的地方要在行尾加入注释，可以在代码之后空两格加行尾注释，如：

// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget - index_->length());
if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
return; // Error already logged.

注意，有两块注释描述这段代码，当函数返回时注释提及错误已经被记入日志。

前后相邻几行都有注释，可以适当调整使之可读性更好：

...
DoSomething(); // Comment here so the comments line up.
DoSomethingElseThatIsLonger(); // Comment here so there are two spaces between
// the code and the comment.
...

NULL、true/false、1、2、3……：

向函数传入、布尔值或整数时，要注释说明含义，或使用常量让代码望文知意，比较一下：

bool success = CalculateSomething(interesting_value,
10,
false,
NULL); // What are these arguments??

和：

bool success = CalculateSomething(interesting_value,
10, // Default base value.
false, // Not the first time we''re calling this.
NULL); // No callback.

使用常量或描述性变量：

const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
Callback *null_callback = NULL;
bool success = CalculateSomethi

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!