title: 《华为C语言编程规范 》 data: 2021-11-7
第一章 排版
-
相对独立的程序块之间、变量说明之后必须加空行。
-
if、for、do、while、case、switch、default等语句各自占一行,且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
-
对其用空格键,不用
Tab
键。 -
对两个以上的关键字、变量、常量进行对等操作时,加空格的情况。
①多重括号间不必加空格;
②"->"、"."前后不加空格;
③if、for、while、switch等与后面的括号间应加空格,使其更突出。
-
一行程序小于80字符为宜,不要过长。
第二章 注释
-
源程序有效注释量必须在20%以上。
-
说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应 进行注释,注释必须列出:版权说明、版本号、生成日期、作者、内容、功能、与其它文件的 关系、修改日志等,头文件的注释中还应有函数功能简要说明。
/************************************************* Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. File name: // 文件名 Author: Version: Date: // 作者、版本及完成日期 Description: // 用于详细说明此程序文件完成的主要功能,与其他模块 // 或函数的接口,输出值、取值范围、含义及参数间的控 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表,每条记录应包括函数名及功能简要说明 1. .... History: // 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述 1. Date: Author: Modification: 2. ... *************************************************/
-
源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、 主要函数及其功能、修改日志等。
/************************************************************ Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. FileName: test.cpp Author: Version : Date: Description: // 模块描述 Version: // 版本信息 Function List: // 主要函数及其功能 1. ------- History: // 历史修改记录 <author> <time> <version > <desc> David 96/10/12 1.0 build this moudle ***********************************************************/
-
函数头部应进行注释,列出:函数的目的/功能、输入参数、输出参数、返回值、调用 关系(函数、表)等。
/************************************************* Function: // 函数名称 Description: // 函数功能、性能等的描述 Calls: // 被本函数调用的函数清单 Called By: // 调用本函数的函数清单 Table Accessed: // 被访问的表(此项仅对于牵扯到数据库操作的程序) Table Updated: // 被修改的表(此项仅对于牵扯到数据库操作的程序) Input: // 输入参数说明,包括每个参数的作用、取值说明及参数间关系。 Output: // 对输出参数的说明。 Return: // 函数返回值的说明 Others: // 其它说明 *************************************************/
-
对代码的注释应放在其上方或右方(对单条语句的注释) 相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
-
对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加 以注释,说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。
-
:数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须 加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注 释放在此域的右方。
-
全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及 存取时注意事项等的说明。
-
注释与所描述内容进行同样的缩排。
-
对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。
-
对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一 个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。
case CMD_DOWN: ProcessDown(); break; case CMD_FWD: ProcessFwd(); ProcessCFW_B(); // now jump into case CMD_A case CMD_A: ProcessA(); break;
12.在程序块的结束行右方加注释标记,以表明某程序块的结束。
说明:当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
if (...) { ... while (index < MAX_INDEX) { ... } /* end of while (index < MAX_INDEX) */ // 指明该条 while 语句结束 } /* end of if (...)*/ // 指明是哪条 if 语句结束