编程规范.docx

1、编程规范编 程 规 范1. 引言今天人们越来越明白软件设计更多地是一种工程，而不是一种个人艺术。由于大型产品的开发通常由很多的人协同作战，如果不统一编程规范，最终合到一起的程序，其可读性将较差，这不仅给代码的理解带来障碍，增加维护阶段的工作量，同时不规范的代码隐含错误的可能性也比较大。BELL实验室的研究资料表明，软件错误中18%左右产生于概要设计阶段，15%左右产生于详细设计阶段，而编码阶段产生的错误占的比例则接近50%；分析表明，编码阶段产生的错误当中，语法错误大概占20%左右，而由于未严格检查软件逻辑导致的错误、函数（模块）之间接口错误及由于代码可理解度低导致优化维护阶段对代码的错误修改

2、引起的错误则占了一半以上。可见，提高软件质量必须降低编码阶段的错误率。如何有效降低编码阶段的错误呢？BELL实验室的研究人员制定了详细的软件编程规范，并培训每一位程序员，最终的结果把编码阶段的错误降至10%左右，同时也降低了程序的测试费用，效果相当显著。本文从代码的可维护性（可读、可理解性、可修改性）、代码逻辑与效率、函数（模块）接口、可测试性四个方面阐述了软件编程规范，规范分成规则和建议两种，其中规则部分为强制执行项目，而建议部分则不作强制，可根据习惯取舍。2.编码规范2.1.排版风格 程序块采用缩进风格编写，缩进为4个空格位。排版不混合使用空格和TAB键。 在两个以上的关键字、变量、常量进

3、行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如），后不应加空格。采用这种松散方式编写代码的目的是使代码更加清晰。例如：(1) 逗号、分号只在后面加空格printf(%d %d %d, a, b, c);(2)比较操作符, 赋值操作符=、 +=，算术操作符+、%，逻辑操作符&、&，位域操作符= MAX_TIME_VALUE) a = b + c;a *= 2;a = b 2;(3)!、+、-、&（地址运算符）等单目操作符前后不加空格*pApple = a;/ 内容操作*与内容之间flag = !bIsEmpty;/ 非操作!与内容之间p

4、 = &cMem;/ 地址操作& 与内容之间i+; / +,-与内容之间(4)-、.前后不加空格p-id = pId; / -指针前后不加空格由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如最内层的括号内侧(即左括号后面和右括号前面)不要加空格，因为在C/C+语言中括号已经是最清晰的标志了。另外，在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。最后，即使留空格，也不要连续留两个以上空格(为了保证缩进和排比留空除外)。 函数体的开始，类的定义，结构的定义，if、for、do、while、switch及case语句中的程序都应采用缩进方

5、式，独占一行并且位于同一列，同时与引用它们的语句左对齐 例如下例不符合规范。for ( . ) . / 程序代码if ( . ) . / 程序代码void DoExam( void ). / 程序代码应如下书写。for ( . ) . / 程序代码if ( . ) . / 程序代码void DoExam( void ). / 程序代码 功能相对独立的程序块之间或for、if、do、while、switch等语句前后应加一空行。例如以下例子不符合规范。例一：if ( ! ValidNi( ni ) ). / 程序代码nRepssnInd = SsnData index .nRepssnIndex

6、 ;nRepssnNi= SsnData index .ni ;例二：char *pContext;intnIndex;long lCounter;pContext = new (CString);if(pContext = NULL)return FALSE;应如下书写例一：if ( ! ValidNi( ni ) ). / 程序代码nRepssnInd = SsnData index .nRepssnIndex ;nRepssnNi= SsnData index .ni ;例二：char *pContext;intnIndex;long lCounter;pContext = new (C

7、String);if(pContext = NULL)return FALSE;if、while、for、case、default、do等语句自占一行。示例：如下例子不符合规范。if(pUserCR = NULL) return;应如下书写：if( pUserCR = NULL )return; 若语句较长（多于80字符），可分成多行写，划分出的新行要进行适应的缩进，使排版整齐，语句可读。memset(pData-pData + pData-nCount, 0,(m_nMax - pData-nCount) * sizeof(LPVOID);CNoTrackObject* pValue =(C

8、NoTrackObject*)_afxThreadData-GetThreadValue(m_nSlot);for ( i = 0, j = 0 ; ( i BufferKeyword WordIndex .nWordLength )& ( j NewKeyword.nWordLength ) ; i + , j + )./ 程序代码 一行最多写一条语句。示例：如下例子不符合规范。rect.length = 0 ;rect.width = 0 ;rect.length = width = 0;都应书写成：rect.length = 0 ;rect.width= 0 ; 对结构成员赋值，等号对齐

9、。示例：rect.top= 0;rect.left = 0;rect.right= 300;rect.bottom= 200; #define的各个字段对齐。以下示例不符合规范#defineMAX_TASK_NUMBER 100#defineLEFT_X10#defineBOTTOM_Y 400应书写成：#defineMAX_TASK_NUMBER100#defineLEFT_X10#defineBOTTOM_Y400 不同类型的操作符混合使用时，使用括号给出优先级。如本来是正确的代码：if( year % 4 = 0 | year % 100 != 0 & year % 400 = 0 )如

10、果加上括号，则更清晰。if(year % 4) = 0 | (year % 100) != 0 & (year % 400) = 0)2.2.可理解性2.2.1.注释注释的原则是有助于对程序的阅读理解，注释不宜太多也不能太少，太少不利于代码理解，太多则会对阅读产生干扰，因此只在必要的地方才加注释，而且注释要准确、易懂、尽可能简洁。注释量一般控制在30%到50%之间。 程序在必要的地方必须有注释，注释要准确、易懂、简洁。例如如下注释意义不大。/* 如果bReceiveFlag 为 TRUE */if ( bReceiveFlag = TRUE)而如下的注释则给出了额外有用的信息。/* 如果mtp

11、 从连接处获得一个消息*/if ( bReceiveFlag = TURE) 注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。示例：如下例子不符合规范。例子1/* 获得系统指针和网络指针的副本 */nRepssnInd = SsnData index .nRepssnIndex ;nRepssnNi= SsnData index .ni ;例子2nRepssnInd = SsnData index .nRepssnIndex ;nRepssnNi= SsnData index .ni ;/*获得系统指针

12、和网络指针的副本 */应如下书写/*获得系统指针和网络指针的副本 */nRepssnInd = SsnData index .nRepssnIndex ;nRepssnNi= SsnData index .ni ; 对于所有的常量，变量，数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其含义。示例：/* 活动任务的数量 */#defineMAX_ACT_TASK_NUMBER1000#defineMAX_ACT_TASK_NUMBER1000/* 带原始用户信息的SCCP接口 */enumSCCP_USER_PRIMITIVEN_UNITDA

13、TA_IND ,/* 向SCCP用户报告单元数据已经到达*/N_UNITDATA_REQ ,/* SCCP用户的单元数据发送请求*/ ； 头文件、源文件的头部，应进行注释。注释必须列出：文件名、作者、目的、功能、修改日志等。例如：/*文件名：编写者：编写日期：简要描述：修改记录：*/说明：每条修改记录应包括修改日期、修改者及修改内容简述。 函数头部应进行注释，列出：函数的目的、功能、输入参数、输出参数、修改日志等。形式如下：/*函数名称：简要描述： / 函数目的、功能等的描述输入：/ 输入参数说明，包括每个参数的作用、取值说明及参数间关系，输出：/ 输出参数的说明， 返回值的说明修改日志：*/

14、对一些复杂的函数，在注释中最好提供典型用法。 仔细定义并明确公共变量的含义、作用、取值范围及使用方法。在对变量声明的同时，应对其含义、作用、取值范围及使用方法进行注释说明，同时若有必要还应说明与其它变量的关系。明确公共变量与操作此公共变量的函数或过程的关系，如访问、修改及创建等。示例：/*SCCP转换时错误代码 */*全局错误代码，含义如下*/ 变量作用、含义/*0 成功1 GT 表错误2 GT 错误其它值 未使用*/ 变量取值范围 对指针进行充分的注释说明，对其作用、含义、使用范围、注意事项等说明清楚。在对指针变量、特别是比较复杂的指针变量声明时，应对其含义、作用及使用范围进行注释说明，如有

15、必要，还应说明其使用方法、注意事项等。示例：/* 学生记录列表的头指针 */*当在此模块中创建该列表时，该头指针必须初始化，*/*这样可以利用GetListHead()获得这一列表。*/指针作用、含义/*该指针只在本模块使用，其它模块通过调用GetListHead()获取*/*当使用时必须保证它非空*/ /使用范围、方法STUDENT_RECORD*pStudentRecHead; 对重要代码段的功能、意图进行注释，提供有用的、额外的信息。并在该代码段的结束处加一行注释表示该段代码结束。示例：/* 可选通道的组合 */if (gsmBCIe31-radioChReq = DUAL_HR_RCR

16、) & (gsmBCIe32-radioChReq = DUAL_HR_RCR)gsmBCIe31-radioChReq = FR_RCR;gsmBCIe32-radioChReq = FR_RCR;else if (gsmBCIe31-radioChReq = DUAL_HR_RCR) & (gsmBCIe32-radioChReq = FR_RCR) )gsmBCIe31-radioChReq = FR_RCR;else if (gsmBCIe31-radioChReq = FR_RCR) & (gsmBCIe32-radioChReq = DUAL_HR_RCR)gsmBCIe32-ra

17、dioChReq = FR_RCR;/* 本块结束 ( 可选通道组合 )*/ 在switch语句中，对没有break语句的case分支加上注释说明。示例：switch(SubT30State)case TA0:AT(CHANNEL, AT+FCLASS=1r, 0);if(T30Status != 0) return(1); InitFax(); /* 准备发送传真 */AT(CHANNEL, ATDr,-1);/*发送CNG ，接收 CED 和 HDLC 标志*/T1_Flg = 1;iResCode = 0;/* 没有 break; */case TA1:iResCode = GetMod

18、emMsg(CHANNEL);break;default:break; 维护代码时，要更新相应的注释，删除不再有用的注释。保持代码、注释的一致性，避免产生误解。2.2 命名本文列出Visual C+的标识符命名规范。 标识符缩写形成缩写的几种技术：1)去掉所有的不在词头的元音字母。如screen写成scrn, primtive写成prmv。2)使用每个单词的头一个或几个字母。如Channel Activation写成ChanActiv，Release Indication写成RelInd。3)使用变量名中每个有典型意义的单词。如Count of Failure写成FailCnt。4)去掉无用的

19、单词后缀 ing, ed等。如Paging Request写成PagReq。5)使用标准的或惯用的缩写形式（包括协议文件中出现的缩写形式）。如BSIC(Base Station Identification Code)、MAP(Mobile Application Part)。关于缩写的准则：1)缩写应该保持一致性。如Channel不要有时缩写成Chan，有时缩写成Ch。Length有时缩写成Len，有时缩写成len。2)在源代码头部加入注解来说明协议相关的、非通用缩写。3)标识符的长度不超过32个字符。 变量命名约定参照匈牙利记法，即作用范围域前缀 + 前缀 + 基本类型 + 变量名其中：前

20、缀是可选项，以小写字母表示；基本类型是必选项，以小写字母表示；变量名是必选项，可多个单词(或缩写)合在一起，每个单词首字母大写。前缀列表如下：前缀意义 举例g_Global 全局变量 g_MyVarm_类成员变量模块级变量 m_ListBox, m_Sizes_static 静态变量 s_Counth Handle 句柄 hWndp Pointer 指针 pTheWordlpLong Point长指针 lpCmda Array 数组 aErr基本类型列表如下：基本类型意义 举例b Boolean bIsOKby Byte byNumc Char cMyChari或n Intger nTestN

21、umberu Unsigned integeruCountul Unsigned LongulTimew Word wParadw Double Word dwParal Long lParaf Float fTotals String sTempsz 结束的字符串szTreesfn Funtion fnAddenm 枚举型 enmDaysx,y x,y坐标 宏和常量的命名。宏和常量的命名规则：单词的字母全部大写，各单词之间用下划线隔开。命名举例：#defineMAX_SLOT_NUM8#defineEI_ENCR_INFO0x07const int MAX_ARRAY 结构和结构成员的命名。

22、结构名各单词的字母均为大写，单词间用下划线连接。可用或不用typedef，但是要保持一致，不能有的结构用typedef，有的又不用。如：typedef struct LOCAL_SPC_TABLE_STRUcharcValid;int nSpcCodeMAX_NET_NUM; LOCAL_SPC_TABLE ;结构成员的命名同变量的命名规则。 枚举和枚举成员的命名。枚举名各单词的字母均为大写，单词间用下划线隔开。枚举成员的命名规则：单词的字母全部大写，各单词之间用下划线隔开；要求各成员的第一个单词相同。命名举例：typdef enum LAPD_ MDL_ASSIGN_REQ,LAPD_MDL

23、_ASSIGN_IND,LAPD_DL_DATA_REQ,LAPD_DL_DATA_IND,LAPD_DL_UNIT_DATA_REQ,LAPD_DL_UNIT_DATA_IND, LAPD_PRMV_TYPE; 类的命名前缀意义 举例C 类 CMyClassCO COM COMMyObjectClassCF COM class factory CFMyClassFactoryI COM interface class IMyInterfaceCImplCOM implementation classCImplMyInterface 函数的命名单词首字母为大写，其余均为小写，单词之间不用下划线

24、。函数名应以一个动词开头。命名举例：void PerformSelfTest(void) ;void ProcChanAct(MSG_CHAN_ACTIV *pMsg, UC MsgLen);2.3.可维护性 在逻辑表达式中使用明确的逻辑判断。示例：如下逻辑表达式不规范。1)if ( strlen(strName) )2)for ( index = MAX_SSN_NUMBER; index ; index - )3)while ( p & *p ) / 假设p为字符指针应改为如下：1)if ( strlen(strName) != 0 )2)for ( index = MAX_SSN_NUM

25、BER; index != 0 ; index - )3)while (p != NULL) & (*p != 0 ) 预编译条件不应分离一完整的语句。不正确：if ( cond = GLRUN)#ifdef DEBUG| (cond = GLWAIT)#endif)正确：#ifdef DEBUGif( cond = GLRUN | cond = GLWAIT )#elseif( cond = GLRUN )#endif 在宏定义中合并预编译条件。不正确：#ifdefEXPORTfor ( i = 0; i MAX_MSXRSM; i+ )#else for ( i = 0; i MAX_MSRSM; i+ )#endif正确：头文件中：#ifdefEXPORT#define MAX_MS_RSMMA