i++,j++)
{
...//programcode
}
¹1-4:
若函数或过程中的参数较长,则要进行适当的划分。
示例:
N7StatStrCompare((BYTE*)&stat_object,
(BYTE*)&(act_task_table[taskno].stat_object),
sizeof(_STAT_OBJECT));
N7StatFlashActDuration(stat_item,frame_id*STAT_TASK_CHECK_NUMBER
+index,stat_object);
¹1-5:
不允许把多个短语句写在一行中,即一行只写一条语句。
示例:
如下例子不符合规范。
rect.length=0;rect.width=0;
应如下书写
rect.length=0;
rect.width=0;
¹1-6:
if、for、do、while、case、switch、default等语句自占一行,且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
示例:
如下例子不符合规范。
if(pUserCR==NULL)return;
应如下书写:
if(pUserCR==NULL)
{
return;
}
¹1-7:
函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格,case语句下的情况处理语句也要遵从语句缩进要求。
¹1-8:
在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如->),后不应加空格。
说明:
采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格,多重括号间不必加空格,因为在C/C++语言中括号已经是最清晰的标志了。
在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。
给操作符留空格时不要连续留两个以上空格。
示例:
(1)逗号只在后面加空格。
inta,b,c;
(2)"!
"、"~"、"++"、"--"、"&"(地址运算符)等单目操作符前后不加空格。
*p='a';//内容操作"*"与内容之间
flag=!
is_empty;//非操作"!
"与内容之间
p=&mem;//地址操作"&"与内容之间
i++;//"++","--"与内容之间
(3)"->"、"."前后不加空格。
p->id=pid;//"->"指针前后不加空格
(4)if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。
if(a>=b&&c>d)
(5)比较操作符,赋值操作符"="、"+="前后加空格,算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后建议加空格。
if(current_time>=MAX_TIME_VALUE)
a=b+c;
a*=2;
a=b^2;
¹1-9:
所有文件最后必须有一个空行,因为某些编译器没有这个空行会有编译错误,另外,没有空行也会引起Sourcesafe的diff工作不正常。
1.2.Windows
¹1-10:
程序块的分界符(如C/C++语言的大括号‘{’和‘}’)应各独占一行并且位于同一列,同时与引用它们的语句左对齐。
在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例:
如下例子不符合规范。
for(...){
...//programcode
}
if(...)
{
...//programcode
}
voidExampleFunc(void)
{
...//programcode
}
应如下书写。
for(...)
{
...//programcode
}
if(...)
{
...//programcode
}
voidExampleFunc(void)
{
...//programcode
}
¹1-11:
C++类的头文件定义,书写顺序为:
1.public类型的变量/数据
2.public类型的函数
3.protected类型的变量/数据
4.protected类型的函数
5.private类型的变量/数据
6.private类型的函数
对于VisualStudioClasswizard生成的内容,最后要按照该顺序整理。
¹1-12:
C++类的头文件定义,相关的变量和函数应该写在一起,归类具有条理性,变量的个数清楚易读。
1.3.嵌入式
¹1-10:
C/C++语言的‘{’应该放在语句末尾,而‘}’与引用它们的语句左对齐。
类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例:
if(xistrue){
wedoy
}
do{
bodyofdo-loop
}while(condition);
if(x==y){
..
}elseif(x>y){
...
}else{
....
}
¹1-11:
对于函数来讲,‘{’与‘}’各占一行。
intfunction(intx)
{
bodyoffunction
}
2.注释
2.1.公共部分
¹2-1:
说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出:
版权说明、功能、修改日志等。
文件头的注释采用以下模板:
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*
*Copyright(c)1999-2005IVTCorporation
*
*Allrightsreserved.
*
---------------------------------------------------------------------------*/
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ModuleName:
HelpFunc.cpp
Abstract:
contents
RevisionHistory:
No.Date,Name,Contents
---------------------------------------------------------------------------*/
¹2-2:
源文件头部应进行注释,列出:
版权说明、模块目的/功能、修改日志等。
文件头的注释采用以下模板:
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*
*Copyright(c)1999-2005IVTCorporation
*
*Allrightsreserved.
*
---------------------------------------------------------------------------*/
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ModuleName:
HelpFunc.cpp
Abstract:
contents
RevisionHistory:
No.Date,Name,Contents
---------------------------------------------------------------------------*/
¹2-3:
函数头部应进行注释,列出:
函数的目的/功能、参数说明、返回值等。
函数的注释采用以下模板:
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Description:
Thisfunctionis
Arguments:
temp_addr[in/out]description(aligned)
Return:
description
---------------------------------------------------------------------------*/
¹2-4:
边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
不再有用的注释要删除。
¹2-5:
注释的内容要清楚、明了,含义准确,防止注释二义性。
说明:
错误的注释不但无益反而有害。
¹2-6:
避免在注释中使用缩写,特别是非常用缩写。
说明:
在使用缩写时或之前,应对缩写进行必要的说明。
¹2-7:
注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面。
示例:
如下例子不符合规范。
例1:
/*getreplicatesubsystemindexandnetindicator*/
repssn_ind=ssn_data[index].repssn_index;
repssn_ni=ssn_data[index].ni;
应如下书写
/*getreplicatesubsystemindexandnetindicator*/
repssn_ind=ssn_data[index].repssn_index;
repssn_ni=ssn_data[index].ni;
¹2-8:
对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。
变量、常量、宏的注释应放在其上方相邻位置或右方。
示例:
/*activestatistictasknumber*/
#defineMAX_ACT_TASK_NUMBER1000
#defineMAX_ACT_TASK_NUMBER1000/*activestatistictasknumber*/
¹2-9:
数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。
对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。
示例:
可按如下形式说明枚举/数据/联合结构。
/*HCILocalPolicy*/
structLocalPolicyStru{
UCHARlocal_role:
2;/*SLR_MASTER,SLR_SLAVEorSLR_MASTER_SLAVE*/
UCHARsec_mode:
2;/*securitymode1,2,3*/
UCHARauto_accept:
1;/*auto-acceptremotebasebandconnectionrequest*/
UCHARpairable:
1;/*parableorunpairable*/
UCHARvisible:
1;/*visibleorunvisible*/
UCHARlk_manage:
1;
};
¹2-10:
全局变量要有较详细的注释,包括对其功能、取值范围、以及存取时注意事项等的说明。
示例:
/*TheErrorCodewhenSCCPtranslate*/
/*GlobalTitlefailure,asfollows*///变量作用、含义
/*0-SUCCESS1-GTTableerror*/
/*2-GTerrorOthers-nouse*///变量取值范围
/*onlyfunctionSCCPTranslate()in*/
/*thismodualcanmodifyit,andother*/
/*modulecanvisititthroughcall*/
/*thefunctionGetGTTransErrorCode()*///使用方法
BYTEg_GTTranErrorCode;
¹2-11:
注释与所描述内容进行同样的缩排。
说明:
可使程序排版整齐,并方便注释的阅读与理解。
示例:
如下例子,排版不整齐,阅读稍感不方便。
voidexample_fun(void)
{
/*codeonecomments*/
CodeBlockOne
/*codetwocomments*/
CodeBlockTwo
}
应改为如下布局。
voidexample_fun(void)
{
/*codeonecomments*/
CodeBlockOne
/*codetwocomments*/
CodeBlockTwo
}
¹2-12:
对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。
说明:
这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。
示例:
caseCMD_UP:
ProcessUp();
break;
caseCMD_DOWN:
ProcessDown();
break;
caseCMD_FWD:
ProcessFwd();
ProcessCFW_B();//nowjumpintocaseCMD_A
caseCMD_A:
ProcessA();
break;
caseCMD_B:
ProcessB();
break;
...
¹2-13:
避免在一行代码或表达式的中间插入注释。
说明:
除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
¹2-14:
注释应该说明程序的功能(What)和/或这样作的原因(Why),而不应该说明是怎样作的(How),怎样作的应该蕴含在代码之中。
½2-1:
通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
说明:
清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
½2-2:
在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说明:
注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
示例:
如下注释意义不大。
/*ifreceive_flagisTRUE*/
if(receive_flag)
而如下的注释则给出了额外有用的信息。
/*ifmtpreceiveamessagefromlinks*/
if(receive_flag)
½2-3:
在程序块的结束行右方加注释标记,以表明某程序块的结束。
说明:
当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
示例:
参见如下例子。
if(...)
{
//programcode
while(index{
//programcode
}/*endofwhile(index}/*endofif(...)*///指明是哪条if语句结束
2.2.Windows
¹2-15:
文件的头部注释以及函数说明注释必须使用IVTCodeComment.dsm的宏工具产生的模板,或者是该宏工具产生的注释的模板的完整拷贝。
2.3.嵌入式
¹2-15:
注释使用“/*……*/”,避免移植性问题。
3.标识符命名
3.1.公共部分
¹3-1:
标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。
说明:
较短的单词可通过去掉“元音”形成缩写;较长的单词可取单词的头几个字母形成缩写;一些单词有大家公认的缩写。
缩写表见附录1。
¹3-2:
命名中若使用特殊约定或缩写,则要有注释说明。
说明:
应该在源文件的开始之处,对文件中所使用的缩写或约定,特别是特殊的缩写,进行必要的注释说明。
¹3-3:
自己特有的命名风格,要自始至终保持一致,不可来回变化。
说明:
个人的命名风格,在符合所在项目组或产品组的命名规则的前提下,才可使用。
(即命名规则中没有规定到的地方才可有个人命名风格)。
¹3-4:
常量和宏全用大写的字母,用下划线分割单词
示例:
/*controllertohostflowcontrolflags*/
#defineHC2HOST_FC_OFF0
#defineHC2HOST_FC_ACL1
#defineHC2HOST_FC_SCO2
#defineHC2HOST_FC_BOTH3
¹3-5:
静态变量加前缀s_
¹3-6:
如果不得已需要全局变量,则全局变量加前缀g_
½3-1:
除非必要,不要用数字或较奇怪的字符来定义标识符。
示例:
如下命名,使人产生疑惑。
#define_EXAMPLE_0_TEST_
#define_EXAMPLE_1_TEST_
voidset_sls00(BYTEsls);
应改为有意义的单词命名
#define_EXAMPLE_UNIT_TEST_
#define_EXAMPLE_ASSERT_TEST_
voidSetUdtMsgSls(BYTEsls);
½3-2:
在同一软件产品内,应规划好接口部分标识符(变量、结构、函数及常量)的命名,防止编译、链接时产生冲突。
说明:
对接口部分的标识符应该有更严格限制,防止冲突。
如可规定接口部分的变量与常量之前加上“模块”标识等。
½3-3:
用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
说明:
下面是一些在软件中常用的反义词组。
add/removebegin/endcreate/destroy
insert/deletefirst/lastget/release
increment/decrementput/get
add/deletelock/unlockopen/close
min/maxold/newstart/stop
next/previoussource/targetshow/hide
send/receivesource/destination
cut/pasteup/down
示例:
intmin_sum;
intmax_sum;
intadd_user(BYTE*user_name);
intdelete_user(BYTE*user_name);
½3-4:
除了编译开关/头文件等特殊应用,应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义。
3.2.Windows
¹3-7:
类名和函数名用大写字母开头的单词组合而成
示例:
LRESULTCAsyncThread:
:
OnSwitchRole(WPARAMwParam,LPARAMlParam)
¹3-8:
变量和参数以小写字母开头,采用大小写混排的方式,并使用匈牙利命名法
匈牙利命名法见附录2
示例:
BOOLCBluetooth:
:
Stop(BOOLbDeviceRemoved);
¹3-9:
成员变量加前缀m_
¹3-10:
对于变量命名,禁止取单个字符(如i、j、k...),建议除了要有具体含义外,还能表明其变量类型、数据类型等,但i、j、k作局部循环变量是允许的。
说明:
变量,尤其是局部变量,如果用单个字符表示,很容易敲错(如i写成j),而编译时又检查不出来,有可能为