基于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