软件编程规范和范例.docx
- 文档编号:12233500
- 上传时间:2023-04-17
- 格式:DOCX
- 页数:64
- 大小:48.27KB
软件编程规范和范例.docx
《软件编程规范和范例.docx》由会员分享,可在线阅读,更多相关《软件编程规范和范例.docx(64页珍藏版)》请在冰豆网上搜索。
软件编程规范和范例
目录
1.排版2
1.1.公共部分2
1.2.Windows5
1.3.嵌入式6
2.注释8
2.1.公共部分8
2.2.Windows12
2.3.嵌入式13
3.标识符命名14
3.1.公共部分14
3.2.Windows15
3.3.嵌入式16
4.可读性17
4.1.公共部分17
4.2.Windows18
5.变量、结构20
5.1.公共部分20
5.2.Windows26
6.函数、过程27
6.1.公共部分27
6.2.Windows36
6.3.嵌入式36
7.可测性37
8.程序效率42
8.1.公共部分42
9.质量保证47
9.1.公共部分47
9.2.Windows51
9.3.嵌入式51
10.代码编辑、编译、审查52
11.代码测试、维护54
12.宏55
12.1.公共部分55
12.2.Windows56
13.附录57
13.1.附录1缩写表57
13.2.附录2匈牙利命名法58
1.排版
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 &&(N7StatItemValid(stat_item)) &&(act_task_table[taskno].result_data! =0)); ¹1-3: 循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在新行之首。 示例: if((taskno =0) &&(N7StatItemValid(stat_item))) { ...//programcode } for(i=0,j=0;(i &&(j { ...//programcode } for(i=0,j=0; (i 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;
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 编程 规范 范例