基于Doxygen的C/C++注释原则

 

基于Doxygen的C/C++注释原则

标注总述

1.文件头标注

2. 命名空间标注

3. 类、结构、枚举标注

4. 函数注释原则

5. 变量注释

6. 模块标注

7. 分组标注

 

 

 

 

 

 

 

 

 

 

 

 

 

总述

如果你使用大多数国内公司使用的编程规范

则遵守以下规则：

1、缩进使用4个空格，不要使用tab

2、独立的程序块之间、变量说明之后必须加空行，如

int tmp;

tmp = MAX_NUM;

3、不要在程序内直接使用数字，应该先将数字进行宏定义后再使用，约定俗成的除外，如

#define MAX_NUM 5

tmp = MAX_NUM

4、所有的大括号开始和大括号结束都另起一行，如

if (!valid_ni(ni))

{

    ... // program code

}

5、每行代码原则上不超过80个字符，长表达式在操作符前换行，如

perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN

                    + STAT_SIZE_PER_FRAM * sizeof( _UL );

act_task_table[frame_id * STAT_TASK_CHECK_NUMBER + index].occupied

                    = stat_poi[index].occupied;

6、一行只写一条语句，**错误**例子如

rect.length = 0; rect.width = 0;

7、if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{ }。

示例：如下例子不符合规范。

if (pUserCR == NULL) return;

应如下书写：

if (pUserCR == NULL)

{

    return;

}

8、在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格，

左括号后面和右括号前面不加空格，逗号、分号只在后面加空格，单目操作福不加空格。如

if (current_time >= MAX_TIME_VALUE)

a = b + c;

a *= 2;

a = b ^ 2;

*p = 'a'; // 内容操作"*"与内容之间

flag = !isEmpty; // 非操作"!"与内容之间

p = &mem; // 地址操作"&" 与内容之间

i++; // "++","--"与内容之间

if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显

if (a >= b && c > d)

9、头文件要加注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明，如

.h头文件

/*******************************************************************************

 * Copyright (C), 1988-1999, Huawei Tech. Co., Ltd.

 * File name:               // 文件名

 * Author: Version: Date:   // 作者、版本及完成日期

 * Description:             // 用于详细说明此程序文件完成的主要功能

 * Others:                  // 其它内容的说明

 * Function List:           // 主要函数列表，每条记录应包括函数名及功能简要说明

 *      1. ....

 * History:                 // 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述

 *      1.  D