软件编码规范(C).docx

《软件编码规范(C).docx》由会员分享，可在线阅读，更多相关《软件编码规范(C).docx（54页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、软件编程规范总则(C/C+)拟制: 审核: 批准:隆承志(仅供内部使用)日期：2003-7-23日期：yyyy-mm-dd日期：yyyy-mm-dd致因尻得Dcampus Networks Co., Ltd.广州数园网络有限公司版权所有侵权必究软件编程规范总则（第一版）为了提高源程序的质量和可维护性，最终提高公司软件产品生产力，我们有必要对公司软件产 品的源程序的编写风格作出统的规范约束。本规范总则是独立于具体语言的编程规则的总的原则，针对不同编程语言或应用环境的编程规 范在遵守本规范总则的基础上，还必须遵守相应语言和就用环境的编程规范。本规范总则适用于公 司所有产品以及对外合作委托开发产品的

2、软件源程序。木规范总则的内容包括：排版、注释、标识符命名、变量使用、代码可测性、程序效率、质量 保证、代码编译、单元测试、程序版本与维护等。本规范总则的示例都以C语言为背景，采用以下的术语描述： 规则：编程时强制必须遵守的原则。 建议：编程时必须加以考虑的原则。 说明：对此规则或建议进行必要的解释。 示例：对此规则或建议从正、反两个方面给出例子。修订记录日期修订版本描述作者2003-8-111.00初稿完成隆承志目录1排版52注释103标识符命名174可读性195变量、结构216函数、过程287可测性378程序效率429质量保证4610代码编辑、编译、审查5311代码测试、维护5512 宏56

3、1排版规则1-1：程序块要采用缩进风格编写，缩进的空格数为4个. 说明：对于由开发工具自动生成的代码可以有不一致。规则1-2：相对独立的程序块之间、变量说明之后必须加空行。 示例：如下例子不符合规范。if (!valid_ni(ni) . / program code )repssn_ind = ssn_dataindex.repssn-index; repssn_ni = ssn_dataindex.ni;应如下书写 if (!valid_ni(ni) . / program code )repssn_ind = ssn_dataindex.repssn_index;repssn_ni =

4、ssn_dataindex.ni;规则1-3：较长的语句(8咛符)要分成多行书写，长表达式要在低优先级操作符处划分新行，操 作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。示例：perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN + STAT_SIZE_PER_FRAM * sizeof( _UL );act_task_tableframe_id * STAT_TASK_CHECK_NUMBER + index.occupied = stat_poiindex.occupied;act_task_tabletaskno

5、.duration_t rue_or_f alse=SYS_get_sccp_statistic_state( stat_item );report_or_not_flag = (taskno MAX_ACT_TASK_NUMBER)& (n7stat_stat_item_valid (stat_item)& (act_task_tabletaskno.result_data != 0);规则1-4：循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优 先级操作符处划分新行，操作符放在新行之首。示例：if (taskno max_act_task_number)& (

6、n7stat_stat_item_valid (stat_item) / program code )for (i = 0, j = 0; (i BufferKeywordword_index.word_length) & (j NewKeyword.word_length); i+, j+) / program code )for (i = 0, j = 0;(i first_word_length) & (j default等语句自占一行，且if、for、do、while等语 句的执行语句部分无论多少都要加括号 O示例：如下例子不符合规范。if (pUserCR = NULL) retur

7、n;应如下书写：if (pUserCR = NULL)(return;)规则18：对齐只使用空格键，不使用TAB键。说明：以免用不同的编辑器阅读程序时，因TAB键所设置的空格数目不同而造成程序布局不整 齐，不要使用BC作为编辑器合版本，因为BC会自动将8个空格变为一个TAB键，因此使用BC 合入的版本大多会将缩进变乱。规则函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语 句下的情况处理语句也要遵从语句缩进要求。规则程序块的分界符(如C/C+语言的大括号，和，)应各独占一行并且位于同一列, 同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的

8、定义以及if、for. do、while、switch、case语句中的程序都要采用如上的缩进方式。示例：如下例子不符合规范。for (. . .) ./ program code)if ()(. / program code)void example_fun( void ), / program code应如下书写。for (.). / program code)if. / program code)void example_fun( void )(. / program code)规则LU:在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者 前后要加空格；进行非对

9、等操作时，如果是关系密切的立即操作符(如一),后不应加空格。说明：采用这种松散方式编写代码的H的是使代码更加清晰。由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的唐句中没有必要再留空格，如 果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加 空格，因为在C/C+语言中括号已经是最清晰的标志了。在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作 符留空格时不要连续留两个以上空格。示例：(1)逗号、分号只在后面加空格。int a, b, c;(2)比较操作符，赋值操作符 = 、算术操作符 +逻辑操作符位域操作符= MAX_T

10、IME_VALUE)a = b + c;a *= 2;a = b A 2;(3)!、一、(地址运算符)等单目操作符前后不加空格。*P = a；/内容操作*与内容之间flag = ! isEmpty; /非操作！与内容之间p = &mem;/地址操作与内容之间i+；/与内容之间(4)前后不加空格.p-id = pid; /指针前后不加空格(5) if、for, while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。 if (a = b & c d)建议一行程序以小于80字符为宜,不要写得过长。2注释规则2-1： 一般情况下，源程序有效注释量必须在20%以上。说明：注释的

11、原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太 少，注释语言必须准确、易懂、简洁。规则2-2：说明性文件(如头文件.h文件、.inc文件、.det文件、编译说明文件.cfg等)头部应进行注 释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改 日志等，头文件的注释中还应有函数功能简要说明。示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含 在内。Copyright (C), 1988-1999, DCampus Network Ltd.File name:/ 文件名Author:Version:Date:

12、 /作者、版本及完成日期Description:/用于详细说明此程序文件完成的主要功能，与其他模块/或函数的接口，输出值、取值范围、含义及参数间的控/制、顺序、独立或依赖等关系Others:/其它内容的说明Function List: /主要函数列表，每条记录应包括函数名及功能简要说明History:/修改历史记录列表，每条修改记录应包括修改日期、修改/者及修改内容简述1. Date:Author:Modification: 2,规则2-3：源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的砌能、 主要函数及其功能、修改日志等.示例：下面这段源文件的头注样比较标准，当然，并

13、不局限于此格式，但上述信息建议要包含 在内。Copyright (C), 1988-1999, Dcampus Network Ltd.FileName: test.cppAuthor:Version :Date:Description:/ 模块描述Version:/版本信息Function List:/主要函数及其功能1. History:/历史修改记录 David 96/10/121.0 build this moudle / 说明：Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它 文件关系等。History是修改历史记录列表，每条修改记录应包括修改口期

14、、修改者及修改内 容简述。规则2-4：函数头部应进行注释，列出：函数的目的硬能、输入参数、输出参数、返回值、调用关 系（函数、表）等。示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。/*Function :/函数名称Description :/函数功能、性能等的描述Calls:/被本函数调用的函数清单Called By:/调用本函数的函数清单Table Accessed: /被访问的表（此项仅对牵扯到数据库操作的程序）Table Updated: /被修改的表（此项仅对于牵扯到数据库操作的程序）Input:/输入参数说明，包括每个参数的作/用、取值说明及参数

15、间关系。Output:/对输出参数的说明。Return:/函数返回值的说明Others:/其它说明规则2-5：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用 的注释要删除。规则2-6：注释的内容要清楚、明了，含义准确，防止注释二义性。说明：错误的注释不但无益反而有害。1.1规则2-7：避免在注释中使用缩写，特别是非常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。规则2-8：注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相 邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。示例：如下例子不符合规范。例1：/*

16、get replicate sub system index and net indicator */repssn_ind = ssn_data index . repssn_index;repssn_ni = ssn_dataindex.ni;例2：repssn_ind = ssn_data index . repssn_index;repssn_ni = ssn_dataindex.ni;/* get replicate sub system index and net indicator */应如下书写/* get replicate sub system index and net i

17、ndicator */ repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;规则2-9：对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以 注释，说明其物理含义.变量、常量、宏的注释应放在其上方相邻位置或右方。示例：/* active statistic task number */#define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */规则

18、2-10：数据结构声明（包括数组、结构、类、枚举等），如果其命名不是充分自注释的，必须加 以注释.对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在 此域的右方。示例：可按如下形式说明枚举/数据/联合结构。/* seep interface with seep user primitive message name */enum SCCP_USER_PRIMITIVE N_UN工TDATA_IND, /* seep notify seep user unit data come */N_NOTICE_INDZ /* seep notify user the No.

19、7 network can not */ /* transmission this message */N_UNITDATA_REQ, /* seep user1s unit data transmission request*/ )；规则2-n：全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存 取时注意事项等的说明.示例：/* The ErrorCode when SCCP translate */* Global Title failure, as follows */ 变量作用、含义/* 0 SUCCESS 1 - GT Table error */* 2 G

20、T error Others no use */ 变量取值范围/* only function SCCPTranslate () in */ this modual can modify it, and other */* module can visit it through call */* the function GetGTTransErrorCode () */ 使用方法BYTE g_GTTranErrorCode;规则2-12：注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便注释的阅读与理解。示例：如卜例子，排版不整齐，阅读稍感不方便。void example_fun

21、( void ) /* code one comments */CodeBlock One/* code two comments */CodeBlock Two)应改为如下布局。void example_fun( void )/* code one comments */ CodeBlock One/* code two comments */ CodeBlock Two )规则2-13：将注释与其上面的代码用空行隔开。 示例：如下例子，显得代码过于紧凑。 / code one comments */ program code one /* code two comments */ prog

22、ram code two应如下书写/* code one comments */ program code one/* code two comments */ program code two规则2-14：对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。说明：这些语句往往是程序实现某一特定功能的关键，对J：维护人员来说，良好的注释帮助更 好的理解程序，有时甚至优于看设计文档。规则2-15：对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case 处理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写

23、者的意图，有效防止无故遗漏break语句。 示例(注意斜体加粗部分)： case CMD_UP:ProcessUp();break;case CMD_DOWN:ProcessDown();break;case CMD_FWD:ProcessFwd();if () break;) else ProcessCFW_B () ;/ now jump into case CMD_A)case CMD_A:ProcessA();break;case CMD_B:ProcessB();break;case CMD_C:ProcessC();break;case CMD_D:ProcessD();break

24、;建议2-1：避免在一行代码或表达式的中间插入注释。说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。 建议2-2：通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为 自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。 建议2-3：在代码的功能、意图层次上进行注释,提供有用、额外的信息.说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理 解代码，防止没必要的重笈注释信息。示例：如下注释意义不大。/* if receive_flag is TRUE */ if (receive_f

25、 lag)而如下的注释则给出了额外有用的信息。/* if mtp receive a message from links */ if (receive_flag)建议2-4：在程序块的结束行右方加注释标记,以表明某程序块的结束。说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。 示例：参见如卜例子。if (.)/ program codewhile (index MAX_INDEX) / program code /* end of while (index AddUser、m_AddUser允许。建议3-1，除非必要,不要用数字或较奇怪的字符来定义标识符。示例：如下

26、命名，使人产生疑惑。#define _EXAMPLE_O_TEST_#define _EXAMPLE_1_TEST_void set_sls00( BYTE sis );应改为有意义的单词命名#define _EXAMPLE_UNIT_TEST.#define _EXAMPLE_ASSERT_TESTvoid set_udt_msg_sls( BYTE sis );建议3-2：在同一软件产品内,应规划好接口部分标识符(变量、结构、函数及常量)的命名,防止编译、链接时产生冲突。说明：对接口部分的标识符应该有更严格限制，防止冲突。如可规定接口部分的变量与常量之前加上“模块”标识等。建议3-3：用正

27、确的反义词组命名具有互斥意义的变量或相反动作的函数等。说明：下面是一些在软件中常用的反义词组。add / removebegin / endcreate / destroyinsert / delete first / lastget / releaseincrement / decrementput / getadd / deletelock / unlockopen / closemin / maxold / newstart / stopnext / previoussource / targetshow / hidesend / receivesource / destinationc

28、ut / pasteup / down示例:intmin_sum;intmax_sum;intadd_user(BYTE *user_name );int建议3-4：delete_user( BYTE *user_name );除了编译开关/头文件等特殊应用,应避免使用_EXAMPLE_TEST_之类以下划线开始和 结尾的定义。建议4可读性规则4-1：注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。示例：下列语句中的表达式word = (high 8) | low (1) if (a I b)

29、& (a & c)(2)if (a I b) (c & d) )(3)如果书写为 high 8 | low a | b & & a & c a | b c & d 由于high 8 | lowhigh 8) | low,a | b & & a & c = (3 | b) & (a & c),(1)(2)不会出错，但语句不易理解；a |bc&d = a I (b Print_Rec、StaJScore为四 个不同的函数；Student、Score为两个全局变量；Create表示创建，Modify表示修改， Access表不访 问。其中，函数Input_Rec、Stat_Score都可修改变量Sc

30、ore,故此变量将引起函数间较大的 耦合，并可能增加代码测试、维护的难度。规则5-4：当向公共变量传递数据时，要十分小心，防止赋与不合理的值或越界等现象发生。说明：对公共变量赋值时，若有必要应进行合法性检查，以提高代码的可靠性、稳定性。规则5.5：防止局部变量与公共变量同名。说明：若使用了较好的命名规则，那么此问题可自动消除。规则5-6：严禁使用未经初始化的变量作为右值。说明：特别是在C/C+中引用未经赋值的指针，经常会引起系统崩溃。建议5-1：构造仅有一个模块或函数可以修改、创建,而其余有关模块或函数只访问的公共变量, 防止多个不同模块或函数都可以修改、创建同一公共变量的现象。说明：降低公共

31、变量耦合度。建议5-2：使用严格形式定义的、可移植的数据类型,尽量不要使用与具体硬件或软件环境关系密切的变量。说明：使用标准的数据类型，有利于程序的移植。示例：如下例子(在DOS下BC3.1环境中)，在移植时可能产生问题。void main() register int index; / 寄存器变量_AX = 0x4000; / _AX是BC3.1提供的寄存器“伪变量” . / program code )建议5-3：结构的功能要单一,是针对一种事务的抽象。说明：设计结构时应力争使结构代表一种现实事务的抽象，而不是同时代表多种。结构中的各 元素应代表同一事务的不同侧面，面不应把描述没有关系或关

32、系很弱的不同事务的元素放到同 一结构中。示例：如下结构不太清晰、合理。typedef struct STUDENT_STRU unsigned char name8; /* student * s name */ unsigned char age;/* student1s age */unsigned char sex;/* student1s sex, as follows */* 0 - FEMALE; 1 - MALE */ unsigned charteacher_name8; /* the student teacher * s name */ unisgned charteach

33、er_sex; /* his teacher sex */ STUDENT;若改为如下，可能更合理些。typedef struct TEACHER_STRU unsigned char name8; /* teacher name */ unisgned char sex; /* teacher sex, as follows */* 0 - FEMALE; 1 - MALE */ TEACHER;unsigned char name8;/* student * s name */unsigned char age;/* student * s age */unsigned char sex;

34、/* student1s sex, as follows */* 0 - FEMALE; 1 - MALE */ unsigned int teacher_ind; /* his teacher index */ STUDENT;建议5-4：不要设计面面俱到、非常灵活的数据结构。说明：面面俱到、灵活的数据结构反而容易引起误解和操作困难。建议5-5：不同结构间的关系不要过于复杂。说明：若两个结构间关系较复杂、密切，那么应合为一个结构。示例：如下两个结构的构造不合理。typedef struct PERSON_ONE_STRUunsigned char name8;unsigned char ad

35、dr40;unsigned char sex;unsigned char city15; PERSON_ONE;typedef struct PERSON_TWO_STRU (unsigned char name8;unsigned char age;unsigned char tel; PERSON_TWO;由于两个结构都是描述同 事物的，那么不如合成个结构。 typedef struct PERSON_STRUunsigned char name8;unsigned char age;unsigned char sex;unsigned char addr40;unsigned char city15;unsigned char tel;)PERSON; 建议5-6：结构中元素的个数应适中。若结构中元素个数过多可考虑依据某种原则把元素组成不同 的子结构,以减少原结构中元素的个数。说明：增加结构的可理解性、可操作性和可维护性。示例：假如认为如上的PERSON结构元素过多，那么可如下对之划分。 typedef struct PERSON_BASE_INFO_STRU unsigned char name8; unsigned c