C51编程规范.docx
《C51编程规范.docx》由会员分享,可在线阅读,更多相关《C51编程规范.docx(37页珍藏版)》请在冰点文库上搜索。
C51编程规范
C51编程:
c51编程规范
(1)
引言
今天人们越来越明白软件设计更多地是一种工程,而不是一种个人艺术。
由于大型产品的开
发通常由很多的人协同作战,如果不统一编程规范,最终合到一起的程序,其可读性将较
差,这不仅给代码的理解带来障碍,增加维护阶段的工作量,同时不规范的代码隐含错误的
可能性也比较大。
BELL实验室的研究资料表明,软件错误中18%左右产生于概要设计阶段,15%左右产生于详细设计阶段,而编码阶段产生的错误占的比例则接近50%;分析表明,编码阶段产生的错误当中,语法错误大概占20%左右,而由于未严格检查软件逻辑导致的错误、函数(模块)之间接口错误及由于代码可理解度低导致优化维护阶段对代码的错误修改引起的错误则占了一半以上。
可见,提高软件质量必须降低编码阶段的错误率。
如何有效降低编码阶段的错误呢?
BELL实验室的研究人员制定了详细的软件编程规范,并培训每一位程序员,最终的结果把编码阶段的错误降至10%左右,同时也降低了程序的测试费用,效果相当显著。
本文从代码的可维护性(可读、可理解性、可修改性)、代码逻辑与效率、函数(模块)接
口、可测试性四个方面阐述了软件编程规范,规范分成规则和建议两种,其中规则部分为强
制执行项目,而建议部分则不作强制,可根据习惯取舍。
2.编码规范
2.1.排版风格
<规则1>程序块采用缩进风格编写,缩进为4个空格位。
排版不混合使用空格和TAB键。
<规则2>在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如->),后不应加空格。
采用这种松散方式编写代码的目的是使代码更加清晰。
例如:
(1)逗号、分号只在后面加空格
printf("%d%d%d",a,b,c);
(2)比较操作符,赋值操作符"="、"+=",算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后加空格
if(lCurrentTime>=MAX_TIME_VALUE)
a=b+c;
a*=2;
a=b^2;
(3)"!
"、"~"、"++"、"--"、"&"(地址运算符)等单目操作符前后不加空格
*pApple='a';//内容操作"*"与内容之间
flag=!
bIsEmpty;//非操作"!
"与内容之间
p=&cMem;//地址操作"&"与内容之间
i++;//"++","--"与内容之间
(4)"->"、"."前后不加空格
p->id=pId;//"->"指针前后不加空格
由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,
如最内层的括号内侧(即左括号后面和右括号前面)不要加空格,因为在C/C++语言中括号已
经是最清晰的标志了。
另外,在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空
格。
最后,即使留空格,也不要连续留两个以上空格(为了保证缩进和排比留空除外)。
<规则3>函数体的开始,类的定义,结构的定义,if、for、do、while、switch及case语句
中的程序都应采用缩进方式,憑捄蛻}捰禀独占一行并且位于同一列,同时与引用它们的语
句左对齐
例如下例不符合规范。
for(...){
...//程序代码
}
if(...)
{
voidDoExam(void)
应如下书写。
for(...)
<规则4>功能相对独立的程序块之间或for、if、do、while、switch等语句前后应加一空
行。
例如以下例子不符合规范。
例一:
if(!
ValidNi(ni))
nRepssnInd=SsnData[index].nRepssnIndex;
nRepssnNi=SsnData[index].ni;
例二:
char*pContext;
intnIndex;
longlCounter;
pContext=new(CString);
if(pContext==NULL)
returnFALSE;
应如下书写
<规则5>if、while、for、case、default、do等语句自占一行。
示例:
如下例子不符合规范。
if(pUserCR==NULL)return;
应如下书写:
if(pUserCR==NULL)
return;
<规则6>若语句较长(多于80字符),可分成多行写,划分出的新行要进行适应的缩进,使
排版整齐,语句可读。
memset(pData->pData+pData->nCount,0,
(m_nMax-pData->nCount)*sizeof(LPVOID));
CNoTrackObject*pValue=
(CNoTrackObject*)_afxThreadData->GetThreadValue(m_nSlot);
for(i=0,j=0;(i&&(j{...//程序代码}<规则7>一行最多写一条语句。示例:如下例子不符合规范。rect.length=0;rect.width=0;rect.length=width=0;都应书写成:rect.length=0;rect.width=0;<规则8>对结构成员赋值,等号对齐。示例:rect.top=0;rect.left=0;rect.right=300;rect.bottom=200;<规则9>#define的各个字段对齐以下示例不符合规范#defineMAX_TASK_NUMBER100#defineLEFT_X10#defineBOTTOM_Y400应书写成:#defineMAX_TASK_NUMBER100#defineLEFT_X10#defineBOTTOM_Y400<规则10>不同类型的操作符混合使用时,使用括号给出优先级。如本来是正确的代码:if(year%4==0||year%100!=0&&year%400==0)如果加上括号,则更清晰。if((year%4)==0||((year%100)!=0&&(year%400)==0))2.2.可理解性2.2.1.注释注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,太少不利于代码理解,太多则会对阅读产生干扰,因此只在必要的地方才加注释,而且注释要准确、易懂、尽可能简洁。注释量一般控制在30%到50%之间。<规则1>程序在必要的地方必须有注释,注释要准确、易懂、简洁。例如如下注释意义不大。/*如果bReceiveFlag为TRUE*/if(bReceiveFlag==TRUE)而如下的注释则给出了额外有用的信息。/*如果mtp从连接处获得一个消息*/if(bReceiveFlag==TURE)<规则2>注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。示例:如下例子不符合规范。例子1/*获得系统指针和网络指针的副本*/nRepssnInd=SsnData[index].nRepssnIndex;nRepssnNi=SsnData[index].ni;例子2nRepssnInd=SsnData[index].nRepssnIndex;nRepssnNi=SsnData[index].ni;/*获得系统指针和网络指针的副本*/应如下书写/*获得系统指针和网络指针的副本*/nRepssnInd=SsnData[index].nRepssnIndex;nRepssnNi=SsnData[index].ni;<规则3>对于所有的常量,变量,数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,在声明时都必须加以注释,说明其含义。示例:/*活动任务的数量*/#defineMAX_ACT_TASK_NUMBER1000#defineMAX_ACT_TASK_NUMBER1000/*活动任务的数量*//*带原始用户信息的SCCP接口*/enumSCCP_USER_PRIMITIVE{N_UNITDATA_IND,/*向SCCP用户报告单元数据已经到达*/N_UNITDATA_REQ,/*SCCP用户的单元数据发送请求*/};<规则4>头文件、源文件的头部,应进行注释。注释必须列出:文件名、作者、目的、功能、修改日志等。例如:/*********************************************文件名:编写者:编写日期:简要描述:修改记录:********************************************/说明:摷蛞枋鰯一项描述本文件的目的和功能等。撔薷募锹紨是修改日志列表,每条修改记录应包括修改日期、修改者及修改内容简述。<规则5>函数头部应进行注释,列出:函数的目的、功能、输入参数、输出参数、修改日志等。形式如下:/*************************************************函数名称:简要描述://函数目的、功能等的描述输入://输入参数说明,包括每个参数的作用、取值说明及参数间关系,输出://输出参数的说明,返回值的说明修改日志:*************************************************/对一些复杂的函数,在注释中最好提供典型用法。<规则6>仔细定义并明确公共变量的含义、作用、取值范围及使用方法。在对变量声明的同时,应对其含义、作用、取值范围及使用方法进行注释说明,同时若有必要还应说明与其它变量的关系。明确公共变量与操作此公共变量的函数或过程的关系,如访问、修改及创建等。示例:/*SCCP转换时错误代码*//*全局错误代码,含义如下*///变量作用、含义/*0-成功1-GT表错误2-GT错误其它值-未使用*///变量取值范围<规则7>对指针进行充分的注释说明,对其作用、含义、使用范围、注意事项等说明清楚。在对指针变量、特别是比较复杂的指针变量声明时,应对其含义、作用及使用范围进行注释说明,如有必要,还应说明其使用方法、注意事项等。示例:/*学生记录列表的头指针*//*当在此模块中创建该列表时,该头指针必须初始化,*//*这样可以利用GetListHead()获得这一列表。*///指针作用、含义/*该指针只在本模块使用,其它模块通过调用GetListHead()获取*//*当使用时必须保证它非空*///使用范围、方法STUDENT_RECORD*pStudentRecHead;<规则8>对重要代码段的功能、意图进行注释,提供有用的、额外的信息。并在该代码段的结束处加一行注释表示该段代码结束。示例:/*可选通道的组合*/if((gsmBCIe31->radioChReq>=DUAL_HR_RCR)&&(gsmBCIe32->radioChReq>=DUAL_HR_RCR)){gsmBCIe31->radioChReq=FR_RCR;gsmBCIe32->radioChReq=FR_RCR;}elseif((gsmBCIe31->radioChReq>=DUAL_HR_RCR)&&(gsmBCIe32->radioChReq==FR_RCR)){gsmBCIe31->radioChReq=FR_RCR;}elseif((gsmBCIe31->radioChReq==FR_RCR)&&(gsmBCIe32->radioChReq>=DUAL_HR_RCR)){gsmBCIe32->radioChReq=FR_RCR;}/*本块结束(可选通道组合)*/<规则9>在switch语句中,对没有break语句的case分支加上注释说明。示例:switch(SubT30State){caseTA0:AT(CHANNEL,"AT+FCLASS=1\r",0);if(T30Status!=0){return(1);}InitFax();/*准备发送传真*/AT(CHANNEL,"ATD\r",-1);/*发送CNG,接收CED和HDLC标志*/T1_Flg=1;iResCode=0;/*没有break;*/caseTA1:iResCode=GetModemMsg(CHANNEL);break;default:break;}<规则10>维护代码时,要更新相应的注释,删除不再有用的注释。保持代码、注释的一致性,避免产生误解。2.2命名本文列出VisualC++的标识符命名规范。<规则1>标识符缩写形成缩写的几种技术:1)去掉所有的不在词头的元音字母。如screen写成scrn,primtive写成prmv。2)使用每个单词的头一个或几个字母。如ChannelActivation写成ChanActiv,ReleaseIndication写成RelInd。3)使用变量名中每个有典型意义的单词。如CountofFailure写成FailCnt。4)去掉无用的单词后缀ing,ed等。如PagingRequest写成PagReq。5)使用标准的或惯用的缩写形式(包括协议文件中出现的缩写形式)。如BSIC(BaseStationIdentificationCode)、MAP(MobileApplicationPart)。关于缩写的准则:1)缩写应该保持一致性。如Channel不要有时缩写成Chan,有时缩写成Ch。Length有时缩写成Len,有时缩写成len。2)在源代码头部加入注解来说明协议相关的、非通用缩写。3)标识符的长度不超过32个字符。<规则2>变量命名约定参照匈牙利记法,即[作用范围域前缀]+[前缀]+基本类型+变量名其中:前缀是可选项,以小写字母表示;基本类型是必选项,以小写字母表示;变量名是必选项,可多个单词(或缩写)合在一起,每个单词首字母大写。前缀列表如下:前缀意义举例g_Global全局变量g_MyVarm_类成员变量或模块级变量m_ListBox,m_Sizes_static静态变量s_CounthHandle句柄hWndpPointer指针pTheWordlpLongPoint长指针lpCmdaArray数组aErr基本类型列表如下:基本类型意义举例bBoolean布尔bIsOKbyByte字节byNumcChar字符cMyChari或nIntger整数nTestNumberuUnsignedinteger无符号整数uCountulUnsignedLong无符号长整数ulTimewWord字wParadwDoubleWord双字dwParalLong长型lParafFloat浮点数fTotalsString字符串sTempszNULL结束的字符串szTreesfnFuntion函数fnAddenm枚举型enmDaysx,yx,y坐标<规则3>宏和常量的命名宏和常量的命名规则:单词的字母全部大写,各单词之间用下划线隔开。命名举例:#defineMAX_SLOT_NUM8#defineEI_ENCR_INFO0x07constintMAX_ARRAY<规则4>结构和结构成员的命名结构名各单词的字母均为大写,单词间用下划线连接。可用或不用typedef,但是要保持一致,不能有的结构用typedef,有的又不用。如:typedefstructLOCAL_SPC_TABLE_STRU{charcValid;intnSpcCode[MAX_NET_NUM];}LOCAL_SPC_TABLE;结构成员的命名同变量的命名规则。<规则5>枚举和枚举成员的命名枚举名各单词的字母均为大写,单词间用下划线隔开。枚举成员的命名规则:单词的字母全部大写,各单词之间用下划线隔开;要求各成员的第一个单词相同。命名举例:typdefenum{LAPD_MDL_ASSIGN_REQ,LAPD_MDL_ASSIGN_IND,LAPD_DL_DATA_REQ,LAPD_DL_DATA_IND,LAPD_DL_UNIT_DATA_REQ,LAPD_DL_UNIT_DATA_IND,}LAPD_PRMV_TYPE;<规则6>类的命名前缀意义举例C类CMyClassCOCOM类COMMyObjectClassCFCOMclassfactoryCFMyClassFactoryICOMinterfaceclassIMyInterfaceCImplCOMimplementationclassCImplMyInterface<规则7>函数的命名单词首字母为大写,其余均为小写,单词之间不用下划线。函数名应以一个动词开头,即函数名应类似摱鼋峁箶。命名举例:voidPerformSelfTest(void);voidProcChanAct(MSG_CHAN_ACTIV*pMsg,UCMsgLen);2.3. 可维护性<规则1> 在逻辑表达式中使用明确的逻辑判断。示例:如下逻辑表达式不规范。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_NUMBER; index != 0 ; index -- )3) while ((p != NULL) && (*p != '\0' ))<规则2> 预编译条件不应分离一完整的语句。不正确:if (( cond == GLRUN)#ifdef DEBUG || (cond == GLWAIT)#endif){ }正确:#ifdef DEBUGif( cond == GLRUN || cond == GLWAIT )#elseif( cond == GLRUN )#endif{ }<规则3> 在宏定义中合并预编译条件。不正确:#ifdef EXPORT for ( i = 0; i < MAX_MSXRSM; i++ )#elsefor ( i = 0; i < MAX_MSRSM; i++ )#endif 正确: 头文件中: #ifdef EXPORT #define MAX_MS_RSM MAX_MSXRSM #else #define MAX_MS_RSM MAX_MSRSM #endif 源文件中: for( i = 0; i < MAX_MS_RSM; i++ )<规则4> 使用宏定义表达式时,要使用完备的括号。如下的宏定义表达式都存在一定的隐患。#define REC_AREA(a, b) a * b#define REC_AREA(a, b) (a * b)#define REC_AREA(a, b) (a) * (b) 正确的定义为: #define REC_AREA(a, b) ((a) * (b))<规则5> 宏所定义的多条表达式应放在大括号内。示例:下面的语句只有宏中的第一条表达式被执行。为了说明问题,for语句的书写稍不符规范。#define INIT_RECT_VALUE( a, b ) a = 0 ; b = 0 ;for ( index = 0 ; index < RECT_TOTAL_NUM ; index ++ ) I
&&(j{...//程序代码}<规则7>一行最多写一条语句。示例:如下例子不符合规范。rect.length=0;rect.width=0;rect.length=width=0;都应书写成:rect.length=0;rect.width=0;<规则8>对结构成员赋值,等号对齐。示例:rect.top=0;rect.left=0;rect.right=300;rect.bottom=200;<规则9>#define的各个字段对齐以下示例不符合规范#defineMAX_TASK_NUMBER100#defineLEFT_X10#defineBOTTOM_Y400应书写成:#defineMAX_TASK_NUMBER100#defineLEFT_X10#defineBOTTOM_Y400<规则10>不同类型的操作符混合使用时,使用括号给出优先级。如本来是正确的代码:if(year%4==0||year%100!=0&&year%400==0)如果加上括号,则更清晰。if((year%4)==0||((year%100)!=0&&(year%400)==0))2.2.可理解性2.2.1.注释注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,太少不利于代码理解,太多则会对阅读产生干扰,因此只在必要的地方才加注释,而且注释要准确、易懂、尽可能简洁。注释量一般控制在30%到50%之间。<规则1>程序在必要的地方必须有注释,注释要准确、易懂、简洁。例如如下注释意义不大。/*如果bReceiveFlag为TRUE*/if(bReceiveFlag==TRUE)而如下的注释则给出了额外有用的信息。/*如果mtp从连接处获得一个消息*/if(bReceiveFlag==TURE)<规则2>注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。示例:如下例子不符合规范。例子1/*获得系统指针和网络指针的副本*/nRepssnInd=SsnData[index].nRepssnIndex;nRepssnNi=SsnData[index].ni;例子2nRepssnInd=SsnData[index].nRepssnIndex;nRepssnNi=SsnData[index].ni;/*获得系统指针和网络指针的副本*/应如下书写/*获得系统指针和网络指针的副本*/nRepssnInd=SsnData[index].nRepssnIndex;nRepssnNi=SsnData[index].ni;<规则3>对于所有的常量,变量,数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,在声明时都必须加以注释,说明其含义。示例:/*活动任务的数量*/#defineMAX_ACT_TASK_NUMBER1000#defineMAX_ACT_TASK_NUMBER1000/*活动任务的数量*//*带原始用户信息的SCCP接口*/enumSCCP_USER_PRIMITIVE{N_UNITDATA_IND,/*向SCCP用户报告单元数据已经到达*/N_UNITDATA_REQ,/*SCCP用户的单元数据发送请求*/};<规则4>头文件、源文件的头部,应进行注释。注释必须列出:文件名、作者、目的、功能、修改日志等。例如:/*********************************************文件名:编写者:编写日期:简要描述:修改记录:********************************************/说明:摷蛞枋鰯一项描述本文件的目的和功能等。撔薷募锹紨是修改日志列表,每条修改记录应包括修改日期、修改者及修改内容简述。<规则5>函数头部应进行注释,列出:函数的目的、功能、输入参数、输出参数、修改日志等。形式如下:/*************************************************函数名称:简要描述://函数目的、功能等的描述输入://输入参数说明,包括每个参数的作用、取值说明及参数间关系,输出://输出参数的说明,返回值的说明修改日志:*************************************************/对一些复杂的函数,在注释中最好提供典型用法。<规则6>仔细定义并明确公共变量的含义、作用、取值范围及使用方法。在对变量声明的同时,应对其含义、作用、取值范围及使用方法进行注释说明,同时若有必要还应说明与其它变量的关系。明确公共变量与操作此公共变量的函数或过程的关系,如访问、修改及创建等。示例:/*SCCP转换时错误代码*//*全局错误代码,含义如下*///变量作用、含义/*0-成功1-GT表错误2-GT错误其它值-未使用*///变量取值范围<规则7>对指针进行充分的注释说明,对其作用、含义、使用范围、注意事项等说明清楚。在对指针变量、特别是比较复杂的指针变量声明时,应对其含义、作用及使用范围进行注释说明,如有必要,还应说明其使用方法、注意事项等。示例:/*学生记录列表的头指针*//*当在此模块中创建该列表时,该头指针必须初始化,*//*这样可以利用GetListHead()获得这一列表。*///指针作用、含义/*该指针只在本模块使用,其它模块通过调用GetListHead()获取*//*当使用时必须保证它非空*///使用范围、方法STUDENT_RECORD*pStudentRecHead;<规则8>对重要代码段的功能、意图进行注释,提供有用的、额外的信息。并在该代码段的结束处加一行注释表示该段代码结束。示例:/*可选通道的组合*/if((gsmBCIe31->radioChReq>=DUAL_HR_RCR)&&(gsmBCIe32->radioChReq>=DUAL_HR_RCR)){gsmBCIe31->radioChReq=FR_RCR;gsmBCIe32->radioChReq=FR_RCR;}elseif((gsmBCIe31->radioChReq>=DUAL_HR_RCR)&&(gsmBCIe32->radioChReq==FR_RCR)){gsmBCIe31->radioChReq=FR_RCR;}elseif((gsmBCIe31->radioChReq==FR_RCR)&&(gsmBCIe32->radioChReq>=DUAL_HR_RCR)){gsmBCIe32->radioChReq=FR_RCR;}/*本块结束(可选通道组合)*/<规则9>在switch语句中,对没有break语句的case分支加上注释说明。示例:switch(SubT30State){caseTA0:AT(CHANNEL,"AT+FCLASS=1\r",0);if(T30Status!=0){return(1);}InitFax();/*准备发送传真*/AT(CHANNEL,"ATD\r",-1);/*发送CNG,接收CED和HDLC标志*/T1_Flg=1;iResCode=0;/*没有break;*/caseTA1:iResCode=GetModemMsg(CHANNEL);break;default:break;}<规则10>维护代码时,要更新相应的注释,删除不再有用的注释。保持代码、注释的一致性,避免产生误解。2.2命名本文列出VisualC++的标识符命名规范。<规则1>标识符缩写形成缩写的几种技术:1)去掉所有的不在词头的元音字母。如screen写成scrn,primtive写成prmv。2)使用每个单词的头一个或几个字母。如ChannelActivation写成ChanActiv,ReleaseIndication写成RelInd。3)使用变量名中每个有典型意义的单词。如CountofFailure写成FailCnt。4)去掉无用的单词后缀ing,ed等。如PagingRequest写成PagReq。5)使用标准的或惯用的缩写形式(包括协议文件中出现的缩写形式)。如BSIC(BaseStationIdentificationCode)、MAP(MobileApplicationPart)。关于缩写的准则:1)缩写应该保持一致性。如Channel不要有时缩写成Chan,有时缩写成Ch。Length有时缩写成Len,有时缩写成len。2)在源代码头部加入注解来说明协议相关的、非通用缩写。3)标识符的长度不超过32个字符。<规则2>变量命名约定参照匈牙利记法,即[作用范围域前缀]+[前缀]+基本类型+变量名其中:前缀是可选项,以小写字母表示;基本类型是必选项,以小写字母表示;变量名是必选项,可多个单词(或缩写)合在一起,每个单词首字母大写。前缀列表如下:前缀意义举例g_Global全局变量g_MyVarm_类成员变量或模块级变量m_ListBox,m_Sizes_static静态变量s_CounthHandle句柄hWndpPointer指针pTheWordlpLongPoint长指针lpCmdaArray数组aErr基本类型列表如下:基本类型意义举例bBoolean布尔bIsOKbyByte字节byNumcChar字符cMyChari或nIntger整数nTestNumberuUnsignedinteger无符号整数uCountulUnsignedLong无符号长整数ulTimewWord字wParadwDoubleWord双字dwParalLong长型lParafFloat浮点数fTotalsString字符串sTempszNULL结束的字符串szTreesfnFuntion函数fnAddenm枚举型enmDaysx,yx,y坐标<规则3>宏和常量的命名宏和常量的命名规则:单词的字母全部大写,各单词之间用下划线隔开。命名举例:#defineMAX_SLOT_NUM8#defineEI_ENCR_INFO0x07constintMAX_ARRAY<规则4>结构和结构成员的命名结构名各单词的字母均为大写,单词间用下划线连接。可用或不用typedef,但是要保持一致,不能有的结构用typedef,有的又不用。如:typedefstructLOCAL_SPC_TABLE_STRU{charcValid;intnSpcCode[MAX_NET_NUM];}LOCAL_SPC_TABLE;结构成员的命名同变量的命名规则。<规则5>枚举和枚举成员的命名枚举名各单词的字母均为大写,单词间用下划线隔开。枚举成员的命名规则:单词的字母全部大写,各单词之间用下划线隔开;要求各成员的第一个单词相同。命名举例:typdefenum{LAPD_MDL_ASSIGN_REQ,LAPD_MDL_ASSIGN_IND,LAPD_DL_DATA_REQ,LAPD_DL_DATA_IND,LAPD_DL_UNIT_DATA_REQ,LAPD_DL_UNIT_DATA_IND,}LAPD_PRMV_TYPE;<规则6>类的命名前缀意义举例C类CMyClassCOCOM类COMMyObjectClassCFCOMclassfactoryCFMyClassFactoryICOMinterfaceclassIMyInterfaceCImplCOMimplementationclassCImplMyInterface<规则7>函数的命名单词首字母为大写,其余均为小写,单词之间不用下划线。函数名应以一个动词开头,即函数名应类似摱鼋峁箶。命名举例:voidPerformSelfTest(void);voidProcChanAct(MSG_CHAN_ACTIV*pMsg,UCMsgLen);2.3. 可维护性<规则1> 在逻辑表达式中使用明确的逻辑判断。示例:如下逻辑表达式不规范。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_NUMBER; index != 0 ; index -- )3) while ((p != NULL) && (*p != '\0' ))<规则2> 预编译条件不应分离一完整的语句。不正确:if (( cond == GLRUN)#ifdef DEBUG || (cond == GLWAIT)#endif){ }正确:#ifdef DEBUGif( cond == GLRUN || cond == GLWAIT )#elseif( cond == GLRUN )#endif{ }<规则3> 在宏定义中合并预编译条件。不正确:#ifdef EXPORT for ( i = 0; i < MAX_MSXRSM; i++ )#elsefor ( i = 0; i < MAX_MSRSM; i++ )#endif 正确: 头文件中: #ifdef EXPORT #define MAX_MS_RSM MAX_MSXRSM #else #define MAX_MS_RSM MAX_MSRSM #endif 源文件中: for( i = 0; i < MAX_MS_RSM; i++ )<规则4> 使用宏定义表达式时,要使用完备的括号。如下的宏定义表达式都存在一定的隐患。#define REC_AREA(a, b) a * b#define REC_AREA(a, b) (a * b)#define REC_AREA(a, b) (a) * (b) 正确的定义为: #define REC_AREA(a, b) ((a) * (b))<规则5> 宏所定义的多条表达式应放在大括号内。示例:下面的语句只有宏中的第一条表达式被执行。为了说明问题,for语句的书写稍不符规范。#define INIT_RECT_VALUE( a, b ) a = 0 ; b = 0 ;for ( index = 0 ; index < RECT_TOTAL_NUM ; index ++ ) I
<规则7>一行最多写一条语句。
rect.length=0;rect.width=0;
rect.length=width=0;
都应书写成:
rect.length=0;
rect.width=0;
<规则8>对结构成员赋值,等号对齐。
rect.top=0;
rect.left=0;
rect.right=300;
rect.bottom=200;
<规则9>#define的各个字段对齐
以下示例不符合规范
#defineMAX_TASK_NUMBER100
#defineLEFT_X10
#defineBOTTOM_Y400
应书写成:
<规则10>不同类型的操作符混合使用时,使用括号给出优先级。
如本来是正确的代码:
if(year%4==0||year%100!
=0&&year%400==0)
如果加上括号,则更清晰。
if((year%4)==0||((year%100)!
=0&&(year%400)==0))
2.2.可理解性
2.2.1.注释
注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,太少不利于代码理解,
太多则会对阅读产生干扰,因此只在必要的地方才加注释,而且注释要准确、易懂、尽可能
简洁。
注释量一般控制在30%到50%之间。
<规则1>程序在必要的地方必须有注释,注释要准确、易懂、简洁。
例如如下注释意义不大。
/*如果bReceiveFlag为TRUE*/
if(bReceiveFlag==TRUE)
而如下的注释则给出了额外有用的信息。
/*如果mtp从连接处获得一个消息*/
if(bReceiveFlag==TURE)
<规则2>注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注
释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
例子1
/*获得系统指针和网络指针的副本*/
例子2
<规则3>对于所有的常量,变量,数据结构声明(包括数组、结构、类、枚举等),如果其命
名不是充分自注释的,在声明时都必须加以注释,说明其含义。
/*活动任务的数量*/
#defineMAX_ACT_TASK_NUMBER1000
#defineMAX_ACT_TASK_NUMBER1000/*活动任务的数量*/
/*带原始用户信息的SCCP接口*/
enumSCCP_USER_PRIMITIVE
N_UNITDATA_IND,/*向SCCP用户报告单元数据已经到达*/
N_UNITDATA_REQ,/*SCCP用户的单元数据发送请求*/
};
<规则4>头文件、源文件的头部,应进行注释。
注释必须列出:
文件名、作者、目的、功
能、修改日志等。
/*********************************************
文件名:
编写者:
编写日期:
简要描述:
修改记录:
********************************************/
说明:
摷蛞枋鰯一项描述本文件的目的和功能等。
撔薷募锹紨是修改日志列表,每条修改
记录应包括修改日期、修改者及修改内容简述。
<规则5>函数头部应进行注释,列出:
函数的目的、功能、输入参数、输出参数、修改日志
等。
形式如下:
/*************************************************
函数名称:
//函数目的、功能等的描述
输入:
//输入参数说明,包括每个参数的作用、取值说明及参数间关
系,
输出:
//输出参数的说明,返回值的说明
修改日志:
*************************************************/
对一些复杂的函数,在注释中最好提供典型用法。
<规则6>仔细定义并明确公共变量的含义、作用、取值范围及使用方法。
在对变量声明的同时,应对其含义、作用、取值范围及使用方法进行注释说明,同时若有必
要还应说明与其它变量的关系。
明确公共变量与操作此公共变量的函数或过程的关系,如访
问、修改及创建等。
/*SCCP转换时错误代码*/
/*全局错误代码,含义如下*///变量作用、含义
/*0-成功1-GT表错误2-GT错误其它值-未使用*///变量
取值范围
<规则7>对指针进行充分的注释说明,对其作用、含义、使用范围、注意事项等说明清楚。
在对指针变量、特别是比较复杂的指针变量声明时,应对其含义、作用及使用范围进行注释
说明,如有必要,还应说明其使用方法、注意事项等。
/*学生记录列表的头指针*/
/*当在此模块中创建该列表时,该头指针必须初始化,*/
/*这样可以利用GetListHead()获得这一列表。
*///指针作用、含义
/*该指针只在本模块使用,其它模块通过调用GetListHead()获取*/
/*当使用时必须保证它非空*///使用范围、方法
STUDENT_RECORD*pStudentRecHead;
<规则8>对重要代码段的功能、意图进行注释,提供有用的、额外的信息。
并在该代码段的
结束处加一行注释表示该段代码结束。
/*可选通道的组合*/
if((gsmBCIe31->radioChReq>=DUAL_HR_RCR)
&&(gsmBCIe32->radioChReq>=DUAL_HR_RCR))
gsmBCIe31->radioChReq=FR_RCR;
gsmBCIe32->radioChReq=FR_RCR;
elseif((gsmBCIe31->radioChReq>=DUAL_HR_RCR)
&&(gsmBCIe32->radioChReq==FR_RCR))
elseif((gsmBCIe31->radioChReq==FR_RCR)
/*本块结束(可选通道组合)*/
<规则9>在switch语句中,对没有break语句的case分支加上注释说明。
switch(SubT30State)
caseTA0:
AT(CHANNEL,"AT+FCLASS=1\r",0);
if(T30Status!
=0)
return
(1);
InitFax();/*准备发送传真*/
AT(CHANNEL,"ATD\r",-1);/*发送CNG,接收CED和HDLC标志*/
T1_Flg=1;
iResCode=0;
/*没有break;*/
caseTA1:
iResCode=GetModemMsg(CHANNEL);
break;
default:
<规则10>维护代码时,要更新相应的注释,删除不再有用的注释。
保持代码、注释的一致性,避免产生误解。
2.2命名
本文列出VisualC++的标识符命名规范。
<规则1>标识符缩写
形成缩写的几种技术:
1)去掉所有的不在词头的元音字母。
如screen写成scrn,primtive写成prmv。
2)使用每个单词的头一个或几个字母。
如ChannelActivation写成ChanActiv,
ReleaseIndication写成RelInd。
3)使用变量名中每个有典型意义的单词。
如CountofFailure写成FailCnt。
4)去掉无用的单词后缀ing,ed等。
如PagingRequest写成PagReq。
5)使用标准的或惯用的缩写形式(包括协议文件中出现的缩写形式)。
如BSIC(Base
StationIdentificationCode)、MAP(MobileApplicationPart)。
关于缩写的准则:
1)缩写应该保持一致性。
如Channel不要有时缩写成Chan,有时缩写成Ch。
Length有时
缩写成Len,有时缩写成len。
2)在源代码头部加入注解来说明协议相关的、非通用缩写。
3)标识符的长度不超过32个字符。
<规则2>变量命名约定
参照匈牙利记法,即
[作用范围域前缀]+[前缀]+基本类型+变量名
其中:
前缀是可选项,以小写字母表示;
基本类型是必选项,以小写字母表示;
变量名是必选项,可多个单词(或缩写)合在一起,每个单词首字母大写。
前缀列表如下:
前缀意义举例
g_Global全局变量g_MyVar
m_类成员变量或模块级变量m_ListBox,m_Size
s_static静态变量s_Count
hHandle句柄hWnd
pPointer指针pTheWord
lpLongPoint长指针lpCmd
aArray数组aErr
基本类型列表如下:
基本类型意义举例
bBoolean布尔bIsOK
byByte字节byNum
cChar字符cMyChar
i或nIntger整数nTestNumber
uUnsignedinteger无符号整数uCount
ulUnsignedLong无符号长整数ulTime
wWord字wPara
dwDoubleWord双字dwPara
lLong长型lPara
fFloat浮点数fTotal
sString字符串sTemp
szNULL结束的字符串szTrees
fnFuntion函数fnAdd
enm枚举型enmDays
x,yx,y坐标
<规则3>宏和常量的命名
宏和常量的命名规则:
单词的字母全部大写,各单词之间用下划线隔开。
命名举例:
#defineMAX_SLOT_NUM8
#defineEI_ENCR_INFO0x07
constintMAX_ARRAY
<规则4>结构和结构成员的命名
结构名各单词的字母均为大写,单词间用下划线连接。
可用或不用typedef,但是要保持一
致,不能有的结构用typedef,有的又不用。
如:
typedefstructLOCAL_SPC_TABLE_STRU
charcValid;
intnSpcCode[MAX_NET_NUM];
}LOCAL_SPC_TABLE;
结构成员的命名同变量的命名规则。
<规则5>枚举和枚举成员的命名
枚举名各单词的字母均为大写,单词间用下划线隔开。
枚举成员的命名规则:
单词的字母全部大写,各单词之间用下划线隔开;要求各成员的第一
个单词相同。
typdefenum
LAPD_MDL_ASSIGN_REQ,
LAPD_MDL_ASSIGN_IND,
LAPD_DL_DATA_REQ,
LAPD_DL_DATA_IND,
LAPD_DL_UNIT_DATA_REQ,
LAPD_DL_UNIT_DATA_IND,
}LAPD_PRMV_TYPE;
<规则6>类的命名
C类CMyClass
COCOM类COMMyObjectClass
CFCOMclassfactoryCFMyClassFactory
ICOMinterfaceclassIMyInterface
CImplCOMimplementationclassCImplMyInterface
<规则7>函数的命名
单词首字母为大写,其余均为小写,单词之间不用下划线。
函数名应以一个动词开头,即函
数名应类似摱鼋峁箶。
voidPerformSelfTest(void);
voidProcChanAct(MSG_CHAN_ACTIV*pMsg,UCMsgLen);
2.3. 可维护性
<规则1> 在逻辑表达式中使用明确的逻辑判断。
如下逻辑表达式不规范。
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_NUMBER; index !
= 0 ; index -- )
3) while ((p !
= NULL) && (*p !
= '\0' ))
<规则2> 预编译条件不应分离一完整的语句。
不正确:
if (( cond == GLRUN)
#ifdef DEBUG
|| (cond == GLWAIT)
#endif
)
正确:
if( cond == GLRUN || cond == GLWAIT )
#else
if( cond == GLRUN )
<规则3> 在宏定义中合并预编译条件。
#ifdef EXPORT
for ( i = 0; i < MAX_MSXRSM; i++ )
for ( i = 0; i < MAX_MSRSM; i++ )
头文件中:
#define MAX_MS_RSM MAX_MSXRSM
#define MAX_MS_RSM MAX_MSRSM
源文件中:
for( i = 0; i < MAX_MS_RSM; i++ )
<规则4> 使用宏定义表达式时,要使用完备的括号。
如下的宏定义表达式都存在一定的隐患。
#define REC_AREA(a, b) a * b
#define REC_AREA(a, b) (a * b)
#define REC_AREA(a, b) (a) * (b)
正确的定义为:
#define REC_AREA(a, b) ((a) * (b))
<规则5> 宏所定义的多条表达式应放在大括号内。
下面的语句只有宏中的第一条表达式被执行。
为了说明问题,for语句的书写稍不符
规范。
#define INIT_RECT_VALUE( a, b ) a = 0 ; b = 0 ;
for ( index = 0 ; index < RECT_TOTAL_NUM ; index ++ )
I
copyright@ 2008-2023 冰点文库 网站版权所有
经营许可证编号:鄂ICP备19020893号-2