C++编码规范之代码注释

注释虽然写起来痛苦但对保证代码可读性至为重要。

1.注释风格

使用// 或/**/统一就好

2.文件注释

在每一个文件开头加入版权公告,然后是文件内容描述

法律公告和作者信息

每一文件包含以下项依次是:

1)版权(copyright statement)

2)许可版本(license boilerplate)

3)作者(author line)：标识文件原始作者

.h文件要多所生命的类的功能和用法做简单说名

.cc文件包含了更多的实现细节或算法讨论。

3.类注释

每一类的定义要附着描述类的功能和用法的注释

//Iterates over the contents of a GargantuanTable.Sample usage

// GargantuanTable_Iterator* iter = table->newIterator()

// for(iter->Seek("foo");!iter->done();iter->Next()){

//     process(iter->key(),iter->value());

// }

//delete iter;

class GargantuanTable_Iterator{

...

};

4.函数注释

函数声明处注释描述函数功能,定义处描述函数实现

函数声明:

注释于声明之前,描述函数功能及用法,注释使用描述式.

函数声明处注释的内容:

1)inputs(输入)及outputs(输出)

2)对类成员函数而言:函数调用期间对象是否需要保持引用参数,是否会释放这些参数

3.如果函数分配了空间,需要由调用者释放

4.参数是否可以是NULL

5.是否存在函数使用性能隐忧(performance implications)

6.如果函数是可重入的其同步前提是什么

函数定义

每个函数定义时要以注释说明函数的功能和实现要点。

5.变量注释

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

类数据成员

每个类数据成员应注释说明用途。如果变量可以接收NULL,-1等警戒值

6.实现注释

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

7.标点,拼写和语法

留意标点,拼写和语法,写得好的注释要比差的易读的多

8.TODO注释

对那些临时的,短期的解决方案或已经够好但并不完美的代码使用TODO注释