C代码编程格式规范

1、C C 代码编程格式规范代码编程格式规范 目目 录录 1 1前言前言 .6 6 2 2适用范围适用范围 .6 6 3 3命名规范命名规范 .6 6 3.1使用的符号、名词及说明.6 3.1.1尖括号 .6 3.1.2大括号 .6 3.1.3圆括号() .7 3.1.4省略号. .7 3.1.5模块定义 .7 3.2标识符的命名.7 3.2.1全局变量 .7 3.2.2局部变量 .7 3.2.3宏定义 .8 3.2.4结构定义 .8 3.2.5目录命名规范 .8 3.2.6程序命名规范 .9 3.2.7函数命名规范 .9 3.2.8数据字典项 .9 3.2.9通用缩写 .9 3.2.10 标识符

2、命名注意问题 .9 4 4注释注释 .1111 4.1一般情况下.11 4.2说明性文件头部注释.11 4.3源文件头部应进行注释.12 4.4函数头部应进行注释.13 4.5书写注释注意事项.13 4.5.1边写代码边注释 .13 4.5.2注释的内容要清楚 .13 4.5.3代码中注释的位置 .14 4.5.4变量、常量的注释方法 .14 4.5.5变量应当成组说明 .14 4.5.6数据结构注释 .15 4.5.7全局变量注释 .15 4.5.8注释与所描述内容进行同样的缩排。 .16 4.5.9将注释与其上面的代码用空行隔开 .16 4.5.10 变量的定义和分支语句 .16 4.5.

3、11 算法说明 .17 4.5.12 特定情况说明 .17 4.5.13 switch 语句.17 4.5.14 无限循环 .17 4.5.15 程序进行修改时注释 .17 5 5书写格式规范书写格式规范 .1717 5.1基本原则.18 5.1.1缩进 .18 5.1.2空行 .18 5.1.3语句的放置 .18 5.1.4续行 .19 5.1.5逗号操作符 .19 5.1.6语句 .20 5.1.7二元操作符 .20 5.2源文件组成结构.20 5.3头文件包含.21 5.4宏定义.21 5.5类型定义.22 5.6外部全局变量声明.23 5.7全局变量定义.23 5.8局部函数声明.24

4、 5.9函数定义部分.24 5.9.1函数头 .24 5.9.2局部变量定义 .25 5.9.3函数正文 .25 5.9.4函数的返回类型说明 .28 5.9.5预处理指令 .28 5.10简单赋值语句 .29 5.11IF语句.29 5.11.1 简单 if 语句结构 .29 5.11.2 if / else 语句结构.30 5.11.3 else-if 链接语句结构.30 5.12WHILE语句结构 .32 5.13FOR语句结构 .32 5.14DO / WHILE()语句结构.32 5.15SWITCH语句结构.33 5.15.1 case 与 default 与保留字 switch

5、保持同一缩进层次.33 5.15.2 每种情况 case 单独成一行。 .33 5.15.3 case 不要用空行分隔开.33 5.15.4 省略了 break 语句 .33 5.15.5 switch 语句的最后一种情况.33 5.16RETURN语句结构.34 6 6编程技巧编程技巧 .3535 6.1寄存器变量.35 6.2尽量不使用GOTO语句.36 6.3WHILE、FOR中使用赋值语句 .36 6.4结构作为参数.36 6.5复合的赋值运算符.36 6.6SIZEOF.37 6.7变量定义同时为其附初值.37 6.8释放内存.37 6.9系统采用统一错误处理机制.37 6.10返回

6、码 .37 7 7性能性能 .3737 7.1可测性.37 7.1.1调测开关的应用 .37 7.1.2调测打印出的信息串的格式要有统一的形式 .38 7.1.3为单元测试选择恰当的测试点 .38 7.1.4构造好测试环境等 .38 7.1.5使用断言来发现软件问题，提高代码可测性 .38 7.1.6用断言来检查调测时有可能发生的非法情况 .39 7.1.7断言检查不了最终产品必须处理的错误 .39 7.1.8对较复杂的断言加上明确的注释 .39 7.1.9用断言确认函数的参数 .39 7.1.10 用断言保证没有定义的特性或功能不被使用 .39 7.1.11 用断言对程序开发环境的假设进行检

7、查 .40 7.1.12 编译器提供的功能及特性假设可用断言检查 .41 7.1.13 正式软件产品去掉断言 .41 7.1.14 测试手段对软件实现的功能不影响 .41 7.1.15 减少维护的难度 .41 7.1.16 DEBUG 版本和发行版本应该统一维护.41 7.1.17 应预先设计好程序调试与测试的方法和手段 .42 7.1.18 调测开关应分为不同级别和类型。 .42 7.1.19 编写防错程序 .42 7.2程序效率.43 7.2.1编程时要经常注意代码的效率 .43 7.2.2局部效率应为全局效率服务 .44 7.2.3提高空间效率 .44 7.2.4循环体内工作量最小化。

8、.45 7.2.5改进模块中函数的组织结构 .46 7.2.6优化代码时，要考虑周全 .46 7.2.7提高调用不频繁的代码效率要慎重 .46 7.2.8压缩代码量，提高空间效率 .46 7.2.9循环的位置 .47 7.2.10 避免循环体内含判断语句 .47 7.2.11 减少判断次数 .48 7.2.12 尽量少用除法 .49 8 8质量保证质量保证 .4949 8.1代码质量保证优先原则.49 8.2只引用属于自己的存贮空间。.50 8.3防止引用已经释放的内存空间。.50 8.4内存，在过程/函数退出之前要释放.50 8.5打开的文件要关闭.50 8.6防止内存操作越界.50 8.7

9、首先初始化有关变量及运行环境.51 8.8一致性检查.51 8.9不能随意改变与其它模块的接口。.52 8.10了解系统的接口之后，再使用系统提供的功能 .52 8.11SWITCH语句必须有DEFAULT分支。 .54 8.12子线程采用主动退出方式 .54 8.13不得使用GOTO语句。.54 8.14其他质量问题 .54 8.15使用变量时要注意其边界值的情况。 .55 8.16留心程序机器码大小 .55 8.17为用户提供良好的接口界面 .55 8.18系统应具有一定的容错能力 .55 8.19防止对数据、硬件等的安全构成危害 .56 8.20第三方提供的软件开发工具包 .56 8.2

10、1资源是对语言敏感的 .56 9 9代码测试、维护代码测试、维护 .5656 1 前言前言 为确保系统源程序可读性，从而增强系统可维护性，C编程人员应具有基本 类似的编程风格，兹制定下述编程规范，以规范系统各部分编程。系统继承的 其它资源中的源程序也应按此规范作相应修改。 2 适用范围适用范围 本文档将作为C编程人员C代码编程格式规范统一版本。在项目的编码、测 试及维护过程中，要求严格遵守。 3 命名规范命名规范 3.1 使用的符号、名词及说明使用的符号、名词及说明 3.1.1 尖括号尖括号 表示括在其中的内容将由一具有实际含义的字符串所代替。例如： #include.h 其中的项目(proj

11、ect)若与 egg-hatch 有关，则实际写成： #includeegg_hatch.h 3.1.2 大括号大括号 在 C 语言中，表示括在其中的内容将是一串具有实际含义的程序语句。 例如： if ( sqlca.sqlcode != 0 ) printf ( Database operation error %dn , sqlca.sqlcode ); exit ( 0 ); 3.1.3 圆括号圆括号() 在 C 语言中，表示括在其中的内容将是函数调用的参数或定义。例如： printf ( Database operation error %dn , sqlca.sqlcode); 3.

12、1.4 省略号省略号. 表示该处可出现一或多条语句。 3.1.5 模块定义模块定义 本文档中所使用的“模块”一词定义为：独立的一组函数与宏，通过 几个明确定义的入口点以及数据结构，共同完成一系列严格定义的、 目的明确的任务。对于该模块的访问只能通过已经形成文档的入口点 进行；该模块内所有其它的数据与代码都局部属于该模块而不能为调 用环境所用。 3.2 标识符的命名标识符的命名 标识符命名要清晰、明了，有明确含义，使用完整的单词。 3.2.1 全局变量全局变量 全局变量：首字母为 g，然后是大小写混排的单词组成 示例： gLessonName、gSize 3.2.2 局部变量局部变量 局部变量：

13、全部小写的单词组成，单词之间使用下划线分割 示例： lesson_name、class_name、size 3.2.3 宏定义宏定义 宏定义：全部大写的单词组成，单词之间使用下划线分割 示例： _LESSON_NAME、_CLASS_NAME、_SIZE 3.2.4 结构定义结构定义 结构定义：结构名使用全部大写的单词组成，单词之间使用下划线分 割，结构成员使用全部小写的单词组成，单词之间使用下划线分割 示例： typedef struct STUDENT_STRU unsigned char name8; /* students name */ unsigned char age; /* s

14、tudents age */ unsigned char sex; /* students sex, as follows */ /* 0 - FEMALE; 1 - MALE */ unsigned char teacher_name8; /* the student teachers name */ unisgned char teacher_sex; /* his teacher sex */ STUDENT; 3.2.5 目录命名规范目录命名规范 目录名只能包含字母字符。目录名不能仅靠字母的大小写不同来区分（尽 管许多操作系统是区分大小写的，但是我们仍然约定：不同的目录名要用不同 的字

15、母进行区分，不能仅靠字母的大小写不同来区分）。目录名的意义应和所 包含内容一致。 3.2.6 程序命名规范程序命名规范 程序包括底层库程序，分目录存放。只含字母，全小写，单词间用“_”线 分格。 例：帐务处理：abc_accproc.pc 3.2.7 函数命名规范函数命名规范 说明：函数名必须首字母大写，多个单词组成的函数名中，每个单词首字 母大写，不能使用下划线分割。函数的参数使用全部小写，单词之间使用下划 线分割。函数内部的局部变量使用全部小写，单词之间使用下划线分割。 3.2.8 数据字典项数据字典项 数据字典中定义的变量就按数据字典中的写法。如： charunit_code10; 3.

16、2.9 通用缩写通用缩写 某些通用的缩写可以使用，如： temp 可缩写为 tmp ; message 可缩写为 msg ; 3.2.10 标识符命名注意问题标识符命名注意问题 除局部循环变量，变量名禁用单个字符除局部循环变量，变量名禁用单个字符 对于变量命名，禁止取单个字符（如i、j、k.），建议除了要有具体含 义外，还能表明其变量类型、数据类型等，但i、j、k作局部循环变量是允许 的。 说明：变量，尤其是局部变量，如果用单个字符表示，很容易敲错（如i写成 j），而编译时又检查不出来，有可能为了这个小小的错误而花费大量的查错时 间。 除非必要，不要用数字或较奇

17、怪的字符来定义标识符。除非必要，不要用数字或较奇怪的字符来定义标识符。 示例：如下命名，使人产生疑惑。 #define _EXAMPLE_0_TEST_ #define _EXAMPLE_1_TEST_ void set_sls00( BYTE sls ); 应改为有意义的单词命名 #define _EXAMPLE_UNIT_TEST_ #define _EXAMPLE_ASSERT_TEST_ void set_udt_msg_sls( BYTE sls ); 在同一软件产品内，应规划好接口部分标识符（变量、结在同一软件产品内，应规划好接口部分标识符（变量、结 构、函数及常量

18、）的命名，防止编译、链接时产生冲突。构、函数及常量）的命名，防止编译、链接时产生冲突。 说明：对接口部分的标识符应该有更严格限制，防止冲突。如可规定 接口部分的变量与常量之前加上“模块”标识等。 用正确的反义词组命名具有互斥意义的变量或相反动作的用正确的反义词组命名具有互斥意义的变量或相反动作的 函数等函数等 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。 说明：下面是一些在软件中常用的反义词组。 add / remove begin / endcreate / destroy insert / deletefirst / last get / release in

19、crement / decrementput / getadd / delete lock / unlock open / closemin / max old / newstart / stopnext/previous source / targetshow / hidesend / receive source / destinationcut / pasteup / down 示例： int minSum; int maxSum; int addUser( BYTE *userName ); int deleteUser( BYTE *userName ); 除了编译开关/头文件、宏定

20、义等特殊应用，应避免使用 _EXAMPLE_TEST_之类以下划线开始和结尾的定义 4 注释注释 4.1 一般情况下一般情况下 源程序有效注释量必须在 20以上。 说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了， 注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 4.2 说明性文件头部注释说明性文件头部注释 说明性文件（如头文件.h 文件、.inc 文件、.def 文件、编译说明文件. cfg 等）头部应进行注释，注释必须列出：版权说明、版本号、内容、 功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数 功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，

21、并不局限于此格式 但上述信息建议要包含在内。 /* Copyright (C), 1988-1999, Nantian Co., Ltd. Version: Description: /用于详细说明此程序文件完成的主要功能 /与其他模块或函数的接口，输出值、取值范围、 含义及参数间的控 /制、顺序、独立或依赖等关系 History: /修改历史记录列表，每条修改记录应包括修改日 期、修改 /者及修改内容简述 date - author - created date - author - modify description */ 4.3 源文件头部应进行注释源文件头部应进行注释 源文件头部应进

22、行注释，列出：版权说明、模块目的/功能、主要函数 及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式， 但上述信息建议要包含在内。 /* Copyright (C), 1988-1999, Nantian Co., Ltd. Description: / 模块描述 Function List: / 主要函数及其功能 1.- 2.- 3.- History: / 历史修改记录 date - author created date - author - modify description */ 说明：Description 一项描述本文件的内容、功能、内部各部分

23、之间的 关系及本文件与其它文件关系等。History 是修改历史记录列表，每条 修改记录应包括修改日期、修改者及修改内容简述。 4.4 函数头部应进行注释函数头部应进行注释 函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、 返回值、调用关系（函数、表）等。 示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但 上述信息建议要包含在内。 /* Function: / 函数名称 Description: / 函数功能、性能等的描述 Table Accessed: / 被访问的表（此项仅对于牵扯到数据库操作的 程序 Table Updated: / 被修改的表（此项仅对于牵扯

24、到数据库操作的 程序） Input: / 输入参数说明，包括每个参数的作 / 用、取值说明及参数间关系。 Output: / 对输出参数的说明。 Return: / 函数返回值的说明 Others: / 其它说明 */ 4.5 书写注释注意事项书写注释注意事项 4.5.1 边写代码边注释边写代码边注释 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码 的一致性。不再有用的注释要删除。 4.5.2 注释的内容要清楚注释的内容要清楚 注释的内容要清楚、明了，含义准确，防止注释二义性。 说明：错误的注释不但无益反而有害。 4.5.3 代码中注释的位置代码中注释的位置 注释应与其描述的代码

25、相近，对代码的注释应放在其上方或右方（对 单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上 面的代码用空行隔开。 注释使用中文书写。示例如下： /*注释行*/ Respond +; 4.5.4 变量、常量的注释方法变量、常量的注释方法 对于所有有物理含义的变量、常量，如果其命名不是充分自注释的， 在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释 应放在其上方相邻位置或右方。 示例： /* active statistic task number */ #define MAX_ACT_TASK_NUMBER 1000 #define MAX_ACT_TASK_NUMBER

26、 1000 /* active statistic task number*/ 4.5.5 变量应当成组说明变量应当成组说明 变量应当成组说明，并且格式整齐，每个变量单独成一行，尾随一单 行注释。如果在一行注释中不可表达清楚，还可以在变量说明之前， 加一个块注释，唯一例外的是一个函数的形式参数，如果它需要一个 块注释，则应将其移至函数头的合适部分。 例：int cnt, /*/ i, /*/ j; /*/ char nameNAME_LEN /*/ 4.5.6 数据结构注释数据结构注释 数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分 自注释的，必须加以注释。对数据结构的注释应放

27、在其上方相邻位置， 不可放在下面；对结构中的每个域的注释放在此域的右方。 示例：可按如下形式说明枚举/数据/联合结构。 /* sccp interface with sccp user primitive message name */ enum SCCP_USER_PRIMITIVE N_UNITDATA_IND, /* sccp notify sccp user unit data come */ N_NOTICE_IND, /* sccp notify user the No.7 network can no */ /* transmission this message */ N_UN

28、ITDATA_REQ, /* sccp users unit data transmission request*/; 4.5.7 全局变量注释全局变量注释 全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或 过程存取它以及存取时注意事项等的说明。 示例： /* The ErrorCode when SCCP translate */ /* Global Title failure, as follows */ / 变量作用、含义 /* 0 SUCCESS 1 GT Table error */ /* 2 GT error Others no use */ / 变量取值范围 /* o

29、nly function SCCPTranslate() in */ /* this modual can modify it, and other */ /* module can visit it through call */ /* the function GetGTTransErrorCode() */ / 使用方法 BYTE g_GTTranErrorCode; 4.5.8 注释与所描述内容进行同样的缩排。注释与所描述内容进行同样的缩排。 说明：可使程序排版整齐，并方便注释的阅读与理解。 示例：如下例子，排版不整齐，阅读稍感不方便。 void ExampleFunction( vo

30、id ) /* code one comments */ CodeBlock One /* code two comments */ CodeBlock Two 应改为如下布局。 void ExampleFunction( void ) /* code one comments */ CodeBlock One /* code two comments */ CodeBlock Two 4.5.9 将注释与其上面的代码用空行隔开将注释与其上面的代码用空行隔开 4.5.10 变量的定义和分支语句变量的定义和分支语句 对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。 说明：这些语句往往

31、是程序实现某一特定功能的关键，对于维护人员 来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。 变量定义时必须加上变量的中文说明； 4.5.11 算法说明算法说明 采用了比较复杂的算法的地方，必须加上算法说明； 4.5.12 特定情况说明特定情况说明 针对特定情况进行处理的地方，必须加上说明； 4.5.13 switch 语句语句 switch 语句中，每个 case 最后都必须是 break 语句。在不写 break 的 地方应该加入注释说明其意图； 4.5.14 无限循环无限循环 在使用无限循环时，应该加入注释说明其退出条件； 4.5.15 程序进行修改时注释程序进行修改时注释

32、在对已经定版的程序进行修改时，要在程序开头的程序说明中加入修 改说明，但在每个修改的地方不用另外说明，老的代码也不用保留； 注释以/*开始，以*/结束，不能嵌套。 5 书写格式规范书写格式规范 严格要求书写格式是为了使程序整齐美观、易于阅读、风格统一，程序员 对规范书写的必要性要有明确认识。 5.1 基本原则基本原则 5.1.1 缩进缩进 采用缩排法表示程序的层次关系。所有函数定义之外的部分（包括头 文件包含、宏定义、全局变量定义、局部函数声明等）全部齐头写， 程序块要采用缩进风格编写，缩进的空格数为 4 个。 说明：对于由开发工具自动生成的代码可以有不一致。 5.1.2 空行空行 程序各部分

33、之间、函数之间、函数内部相对独立的操作之间要加入空 行以示分隔。 5.1.3 语句的放置语句的放置 可执行语句应当单独成一行，并从它所在的开始花括号层缩进一个制 表符宽度。本规则同样适用于空语句，如下所示： if (name_p = (char *) NULL) return;/* WRONG */ while (*target+ = *source+);/* WRONG */ for (i = 0; *target+ = sourcei; i+);/* WRONG */ 上述语句的正确形式如下： if (name_p = (char *) NULL) return;/* Correct */

34、 while (*target+ = *source+) ;/* Correct */ for (i = 0; *target+ = sourcei; i+) ;/* Correct */ 所有的 C 保留字后面均应尾随一空格。例如： while (a b) .; for (i = 0; i 100 字符）要分成多行书写，长表达式要在低优先级操 作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的 缩进，使排版整齐，语句可读 5.1.5 逗号操作符逗号操作符 逗号操作符不应当作为语句分隔符使用。下例错误地使用了逗号操作 符： if (reserved_point(queue_p) sa

35、ve_point(curr_p), queue_p+; 正确的写法应为： if (reserved_point(queue_p) save_point(curr_p); queue_p+; 逗号操作符的正确用法应为：当多个表达式必须在同一个语句中被执 行计算时使用。例如一个 for 语句需要同时修改其它两个变量： cctp = stp = for (site = 1; site numopens = 0, d-available = 1, return(d-next) 5.1.6 语句语句 可执行语句应当单独成一行，并从它所在的开始花括号层缩进一个制 表符宽度。本规则同样适用于空语句。 例：i

36、f (name_p = (char *) NULL) return; 5.1.7 二元操作符二元操作符 二元操作符的前后都必须放一空格(-与.除外，其前后不用放置任何 空格)。一元操作符与操作数之间不用放置任何空格。例如： if (!auditing 5.2 源文件组成结构源文件组成结构 一个 C 源文件中各个部分的布局如下所示。相关的语句应当组成块 (block)的结构，块的布局如下所示。块之间至少由一空行隔开。典型的 源程序依次包含以下部分： （1） 序注释（必须） ； （2） 头文件包含； （3） 宏定义； （4） 类型定义； （5） 全局变量定义； （6） 局部函数声明； （7） 函数

37、定义（必须） 。 除了注明为必须的部分，其余部分视不同程序可选，但一旦出现，则 必须严格按以上次序。各部分之间应该加上必要的空行。注释视需要 穿插在整个文件中。源程序行数应该控制在 1000 行以内，超过 1000 行的可以进行拆分。源程序书写上严格按照本文第 7 章要求的格式。 下面按照模块的组成顺序依次说明。 5.3 头文件包含头文件包含 包含头文件次序为：系统头文件、应用系统公用头文件、应用头文件、 PC 头文件。其中系统头文件用尖括号包含，其他头文件用双引号包含， PC 头文件用 EXEC SQL INCLUDE 包含，而且包含语句用分号结尾。 例如： #include #includ

38、e #include“secure.h” #include“sys_accounting.h” EXEC SQL INCLUDE“dbstruct.h”; 应用系统公用头文件由平台改造小组统一发布。 PC 头文件（定义数据库结构）在开发开始之前由各设计大组随函数库 一起统一发布，应用头文件统一由各子系统组长编辑产生，程序员不 得自行编辑头文件。 5.4 宏定义宏定义 通用的宏应该在公用头文件中定义，这里只应该定义本文件中使用的 宏。 本规范要求不得在程序中直接书写立即数（如：5,n,3.等），而应该 将其定义为宏。 在定义有参数的宏以及常数宏是负数时，注意加上必要的括号，以免 预编译进行宏替换时改变运算次序。例如： #define ADD(a,b)(a) + (b) #define ETPCALL(-1) 如果宏名可能与头文件中定义的重复，则应该加上条件编译。例如： #ifndef BYTE #define BYTEunsigned char #endif /* BYTE */ 把几个语句定义为一个宏的做法虽然可以简化书写过程，但降低了程 序的可读性，不建议使用。 5.5 类型定义类型定义 通用的类型应该在公用头文件中定义，这里只应该定义本文件中使用 的类型。 结构都必须定义相应的类型。在程序中，除了定义结构类型的地方， 其他地