软件编程规范和范例Word格式.docx
- 文档编号:4415260
- 上传时间:2023-05-03
- 格式:DOCX
- 页数:64
- 大小:48.27KB
软件编程规范和范例Word格式.docx
《软件编程规范和范例Word格式.docx》由会员分享,可在线阅读,更多相关《软件编程规范和范例Word格式.docx(64页珍藏版)》请在冰点文库上搜索。
1.1.公共部分
¹
1-1:
程序块要采用缩进风格编写,缩进为Tab(设定为4个字符)或者4个空格。
同一个项目必须保持一致.
说明:
对于由开发工具自动生成的代码可以有不一致。
1-2:
较长的语句(>
80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。
示例:
perm_count_msg.head.len=NO7_TO_STAT_PERM_COUNT_LEN
+STAT_SIZE_PER_FRAM*sizeof(_UL);
act_task_table[frame_id*STAT_TASK_CHECK_NUMBER+index].occupied
=stat_poi[index].occupied;
report_or_not_flag=((taskno<
MAX_ACT_TASK_NUMBER)
&
&
(N7StatItemValid(stat_item))
(act_task_table[taskno].result_data!
=0));
1-3:
循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在新行之首。
if((taskno<
max_act_task_number)&
(taskid!
=0)
&
(N7StatItemValid(stat_item)))
{
...//programcode
}
for(i=0,j=0;
(i<
buffer_keyword[word_index].word_length)
(j<
new_keyword.word_length);
i++,j++)
first_word_length)&
second_word_length);
...//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.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(...){
if(...)
{
}
voidExampleFunc(void)
应如下书写。
for(...)
1-11:
C++类的头文件定义,书写顺序为:
1.public类型的变量/数据
2.public类型的函数
3.protected类型的变量/数据
4.protected类型的函数
5.private类型的变量/数据
6.private类型的函数
对于VisualStudioClasswizard生成的内容,最后要按照该顺序整理。
1-12:
C++类的头文件定义,相关的变量和函数应该写在一起,归类具有条理性,变量的个数清楚易读。
1.3.嵌入式
C/C++语言的‘{’应该放在语句末尾,而‘}’与引用它们的语句左对齐。
类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
if(xistrue){
wedoy
do{
bodyofdo-loop
}while(condition);
if(x==y){
..
}elseif(x>
y){
...
}else{
....
对于函数来讲,‘{’与‘}’各占一行。
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:
源文件头部应进行注释,列出:
版权说明、模块目的/功能、修改日志等。
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;
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:
/*securitymode1,2,3*/
UCHARauto_accept:
1;
/*auto-acceptremotebasebandconnectionrequest*/
UCHARpairable:
/*parableorunpairable*/
UCHARvisible:
/*visibleorunvisible*/
UCHARlk_manage:
};
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
应改为如下布局。
/*codeonecomments*/
2-12:
对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。
这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。
caseCMD_UP:
ProcessUp();
break;
caseCMD_DOWN:
ProcessDown();
caseCMD_FWD:
ProcessFwd();
ProcessCFW_B();
//nowjumpintocaseCMD_A
caseCMD_A:
ProcessA();
caseCMD_B:
ProcessB();
...
2-13:
避免在一行代码或表达式的中间插入注释。
除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
2-14:
注释应该说明程序的功能(What)和/或这样作的原因(Why),而不应该说明是怎样作的(How),怎样作的应该蕴含在代码之中。
½
通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
在代码的功能、意图层次上进行注释,提供有用、额外的信息。
注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
如下注释意义不大。
/*ifreceive_flagisTRUE*/
if(receive_flag)
而如下的注释则给出了额外有用的信息。
/*ifmtpreceiveamessagefromlinks*/
在程序块的结束行右方加注释标记,以表明某程序块的结束。
当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
参见如下例子。
if(...)
//programcode
while(index<
MAX_INDEX)
}/*endofwhile(index<
MAX_INDEX)*///指明该条while语句结束
}/*endofif(...)*///指明是哪条if语句结束
2.2.Windows
2-15:
文件的头部注释以及函数说明注释必须使用IVTCodeComment.dsm的宏工具产生的模板,或者是该宏工具产生的注释的模板的完整拷贝。
2.3.嵌入式
注释使用“/*……*/”,避免移植性问题。
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_
除非必要,不要用数字或较奇怪的字符来定义标识符。
如下命名,使人产生疑惑。
#define_EXAMPLE_0_TEST_
#define_EXAMPLE_1_TEST_
voidset_sls00(BYTEsls);
应改为有意义的单词命名
#define_EXAMPLE_UNIT_TEST_
#define_EXAMPLE_ASSERT_TEST_
voidSetUdtMsgSls(BYTEsls);
在同一软件产品内,应规划好接口部分标识符(变量、结构、函数及常量)的命名,防止编译、链接时产生冲突。
对接口部分的标识符应该有更严格限制,防止冲突。
如可规定接口部分的变量与常量之前加上“模块”标识等。
用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
下面是一些在软件中常用的反义词组。
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;
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 编程 规范 范例