软件编程标准和范例.docx
- 文档编号:8075230
- 上传时间:2023-01-28
- 格式:DOCX
- 页数:50
- 大小:46.97KB
软件编程标准和范例.docx
《软件编程标准和范例.docx》由会员分享,可在线阅读,更多相关《软件编程标准和范例.docx(50页珍藏版)》请在冰豆网上搜索。
软件编程标准和范例
软件编程标准和范例
————————————————————————————————作者:
————————————————————————————————日期:
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; 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),而编译时又检查不出来,有可能为
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 编程 标准 范例