软件编程规范总则33193138811.docx

软件编程规规范总则目 录1 排版62 注释113 标识符符命名184 可读性性205 变量、结结构226 函数、过过程287 可测性性368 程序效效率409 质量保保证4410 代码码编辑、编编译、审查查5011 代码码测试、维维护5212 宏531 排版¹ 1-1：程程序块要采采用缩进风风格编写，缩缩进的空格格数为4个。说明：对于于由开发工工具自动生生成的代码码可以有不不一致。¹ 1-2：相相对独立的的程序块之之间、变量量说明之后后必须加空空行。示例：如下下例子不符符合规范。if (!valiid_nii(ni) . / prrograam cooderepsssn_innd = ssn_dataainddex.repsssn_iindexx;repsssn_nii = ssn_dataainddex.ni;应如下书写写if (!valiid_nii(ni) . / prrograam cooderepsssn_innd = ssn_dataainddex.repsssn_iindexx;repsssn_nii = ssn_dataainddex.ni;¹ 1-3：较较长的语句句（>800字符）要要分成多行行书写，长长表达式要要在低优先先级操作符符处划分新新行，操作作符放在新新行之首，划划分出的新新行要进行行适当的缩缩进，使排排版整齐，语语句可读。示例：perm_counnt_mssg.heead.llen = NO77_TO_STATT_PERRM_COOUNT_LEN + SSTAT_SIZEE_PERR_FRAAM * sizeeof( _UL );act_ttask_tabllefrrame_id * STAAT_TAASK_CCHECKK_NUMMBER + inndex.occcupieed = sstat_poiindeex.ooccuppied;act_ttask_tablletaasknoo.duuratiion_ttrue_or_ffalsee = SSYS_gget_ssccp_stattistiic_sttate( staat_ittem );reporrt_orr_nott_flaag = (taasknoo < MMAX_AACT_TTASK_NUMBBER) && (n7sstat_statt_iteem_vaalid (staat_ittem) && (actt_tassk_taabletaskkno.resuult_ddata != 00);¹ 1-4：循循环、判断断等语句中中若有较长长的表达式式或语句，则则要进行适适应的划分分，长表达达式要在低低优先级操操作符处划划分新行，操操作符放在在新行之首首。示例：if (taskkno << maxx_actt_tassk_nuumberr) &&& (nn7staat_sttat_iitem_valiid (sstat_itemm) . / prrograam coodefor (i = 0, jj = 00; (ii < BBuffeerKeyyworddworrd_inndex.worrd_leengthh) &&& (jj < NNewKeeyworrd.woord_llengtth); i+, j+) . / prrograam coodefor (i = 0, jj = 00; (i << firrst_wword_lenggth) && (j < secoond_wword_lenggth); i+, j+) . / prrograam coode ¹ 1-5：若若函数或过过程中的参参数较长，则则要进行适适当的划分分。示例：n7staat_sttr_coomparre(BBYTE *) && staat_obbjectt, (BBYTE *) && (acct_taask_ttableetasskno.staat_obbjectt), siizeoff (_SSTAT_OBJEECT);n7staat_fllash_act_duraationn( sttat_iitem, fraame_iid *SSTAT_TASKK_CHEECK_NNUMBEER + iindexx, sttat_oobjecct );¹ 1-6：不不允许把多多个短语句句写在一行行中，即一一行只写一一条语句。示例：如下下例子不符符合规范。rect.lenggth = 0; recct.wiidth = 0;应如下书写写rect.lenggth = 0;rect.widtth = 0;¹ 1-7：iif、for、do、whille、casee、swittch、defaault等等语句自占占一行，且且if、for、do、whille等语句句的执行语语句部分无无论多少都都要加括号号。 示例：如下下例子不符符合规范。if (ppUserrCR = NUULL) retuurn;应如下书写写：if (ppUserrCR = NUULL) rreturrn;¹ 1-8：对对齐只使用用空格键，不不使用TAAB键。说明：以免免用不同的的编辑器阅阅读程序时时，因TAAB键所设设置的空格格数目不同同而造成程程序布局不不整齐，不要使用用BC作为编编辑器合版版本，因为为BC会自动动将8个空格变变为一个TTAB键，因因此使用BBC合入的的版本大多多会将缩进进变乱。¹ 1-9：函函数或过程程的开始、结结构的定义义及循环、判判断等语句句中的代码码都要采用用缩进风格格，casse语句下下的情况处处理语句也也要遵从语语句缩进要要求。¹ 1-10：程序块的的分界符（如如C/C+语言的的大括号和）应各独独占一行并并且位于同同一列，同同时与引用用它们的语语句左对齐齐。在函数数体的开始始、类的定定义、结构构的定义、枚枚举的定义义以及iff、for、do、whille、swittch、casee语句中的的程序都要要采用如上上的缩进方方式。示例：如下下例子不符符合规范。for (.) . / prrograam coodeif (.) . / prrograam coode void exammple_fun( voiid ) . / prrograam coode 应如下书写写。for (.) . / prrograam coodeif (.) . / prrograam coodevoid exammple_fun( voiid ) . / prrograam coode¹ 1-11：在两个以以上的关键键字、变量量、常量进进行对等操操作时，它它们之间的的操作符之之前、之后后或者前后后要加空格格；进行非非对等操作作时，如果果是关系密密切的立即即操作符（如如>），后不不应加空格格。说明：采用用这种松散散方式编写写代码的目目的是使代代码更加清清晰。由于留空格格所产生的的清晰性是是相对的，所所以，在已已经非常清清晰的语句句中没有必必要再留空空格，如果果语句已足足够清晰则则括号内侧侧(即左括号号后面和右右括号前面面)不需要加加空格，多多重括号间间不必加空空格，因为为在C/CC+语言言中括号已已经是最清清晰的标志志了。在长语句中中，如果需需要加的空空格非常多多，那么应应该保持整整体清晰，而而在局部不不加空格。给给操作符留留空格时不不要连续留留两个以上上空格。示例：(1) 逗逗号、分号号只在后面面加空格。int aa, b, c; (2)比较较操作符, 赋值操操作符"="、 "+="，算术术操作符""+"、"%"，逻逻辑操作符符"&&"、"&"，位位域操作符符"<<""、""等双双目操作符符的前后加加空格。if (ccurreent_ttime >= MMAX_TTIME_VALUUE) a = bb + cc;a *= 2;a = bb 22;(3)"!"、""、"+""、"-""、"&"（地地址运算符符）等单目目操作符前前后不加空空格。*p = 'a' / 内内容操作""*"与内内容之间flag = !iisEmppty; / 非非操作"!"与内容容之间p = &&mem; / 地地址操作""&" 与与内容之间间i+; / ""+","-""与内容之之间(4)"->"、"."前后后不加空格格。p->idd = ppid; / ""->"指指针前后不不加空格(5) iif、for、whille、swittch等与与后面的括括号间应加加空格，使使if等关键键字更为突突出、明显显。if (aa >= b &&& c >> d)½ 1-1：一一行程序以以小于800字符为宜宜，不要写写得过长。 2 注释¹ 2-1：一一般情况下下，源程序序有效注释释量必须在在20以上上。说明：注释释的原则是是有助于对对程序的阅阅读理解，在在该加的地地方都加了了，注释不不宜太多也也不能太少少，注释语语言必须准准确、易懂懂、简洁。¹ 2-2：说说明性文件件（如头文文件.h文件、.iinc文件件、.deef文件、编编译说明文文件.cffg等）头头部应进行行注释，注注释必须列列出：版权权说明、版版本号、生生成日期、作作者、内容容、功能、与与其它文件件的关系、修修改日志等等，头文件件的注释中中还应有函函数功能简简要说明。示例：下面面这段头文文件的头注注释比较标标准，当然然，并不局局限于此格格式，但上上述信息建建议要包含含在内。/* Coppyrigght (C), 19888-19999, HHuaweei Teech. Co., Ltdd. Fille naame: / 文件名 Autthor: VVersiion: DDate: / 作者、版版本及完成成日期 Desscripptionn: / 用于详细细说明此程程序文件完完成的主要要功能，与与其他模块块 / 或函数的的接口，输输出值、取取值范围、含含义及参数数间的控 / 制、顺序序、独立或或依赖等关关系 Othhers: / 其它内容容的说明 Funnctioon Liist: / 主要函数数列表，每每条记录应应包括函数数名及功能能简要说明明 11. . Hisstoryy: / 修改历史史记录列表表，每条修修改记录应应包括修改改日期、修修改 / 者及修改改内容简述述 11. Daate: Auuthorr: Moodifiicatiion: 22. .*/¹ 2-3：源源文件头部部应进行注注释，列出出：版权说说明、版本本号、生成成日期、作作者、模块块目的/功能、主主要函数及及其功能、修修改日志等等。示例：下面面这段源文文件的头注注释比较标标准，当然然，并不局局限于此格格式，但上上述信息建建议要包含含在内。/* Coppyrigght (C), 19888-19999, HHuaweei Teech. Co., Ltdd. FilleNamme: ttest.cpp Autthor: Verssion : DDate: Desscripptionn: / 模块描描述 Verrsionn: / 版本信信息 Funnctioon Liist: / 主要函函数及其功功能 11. - Hisstoryy: / 历史修修改记录 <auuthorr> <<timee> <verrsionn > <deesc> Davvid 966/10/12 11.0 bbuildd thiis mooudlee */说明：Deescriiptioon一项描描述本文件件的内容、功功能、内部部各部分之之间的关系系及本文件件与其它文文件关系等等。Hisstoryy是修改历历史记录列列表，每条条修改记录录应包括修修改日期、修修改者及修修改内容简简述。¹ 2-4：函函数头部应应进行注释释，列出：函数的目目的/功能、输输入参数、输输出参数、返返回值、调调用关系（函函数、表）等等。示例：下面面这段函数数的注释比比较标准，当当然，并不不局限于此此格式，但但上述信息息建议要包包含在内。/* Funnctioon: / 函数名称称 Desscripptionn: / 函数功能能、性能等等的描述 Callls: / 被本函数数调用的函函数清单 Callled By: / 调用本函函数的函数数清单 Tabble AAccesssed: / 被访问的的表（此项项仅对于牵牵扯到数据据库操作的的程序） Tabble UUpdatted: / 被修改的的表（此项项仅对于牵牵扯到数据据库操作的的程序） Inpput: / 输入参数数说明，包包括每个参参数的作 / 用、取值值说明及参参数间关系系。 Outtput: / 对输出参参数的说明明。 Retturn: / 函数返回回值的说明明 Othhers: / 其它说明明*/¹ 2-5：边边写代码边边注释，修修改代码同同时修改相相应的注释释，以保证证注释与代代码的一致致性。不再再有用的注注释要删除除。¹ 2-6：注注释的内容容要清楚、明明了，含义义准确，防防止注释二二义性。说明：错误误的注释不不但无益反反而有害。规则2-77：避免在在注释中使使用缩写，特特别是非常常用缩写。说明：在使使用缩写时时或之前，应应对缩写进进行必要的的说明。¹ 2-8：注注释应与其其描述的代代码相近，对对代码的注注释应放在在其上方或或右方（对对单条语句句的注释）相相邻位置，不不可放在下下面，如放放于上方则则需与其上上面的代码码用空行隔隔开。示例：如下下例子不符符合规范。例1：/* geet reepliccate sub systtem iindexx andd nett inddicattor */repsssn_innd = ssn_dataainddex.repsssn_iindexx;repsssn_nii = sssn_ddataindeex.nni;例2：repsssn_innd = ssn_dataainddex.repsssn_iindexx;repsssn_nii = sssn_ddataindeex.nni;/* geet reepliccate sub systtem iindexx andd nett inddicattor */应如下书写写/* geet reepliccate sub systtem iindexx andd nett inddicattor */repsssn_innd = ssn_dataainddex.repsssn_iindexx;repsssn_nii = sssn_ddataindeex.nni;¹ 2-9：对对于所有有有物理含义义的变量、常常量，如果果其命名不不是充分自自注释的，在在声明时都都必须加以以注释，说说明其物理理含义。变变量、常量量、宏的注注释应放在在其上方相相邻位置或或右方。示例：/* acctivee staatisttic ttask numbber */#defiine MMAX_AACT_TTASK_NUMBBER 11000#defiine MMAX_AACT_TTASK_NUMBBER 11000 /* aactivve sttatisstic taskk nummber */¹ 2-10：数据结构构声明(包括数组组、结构、类类、枚举等等)，如果其其命名不是是充分自注注释的，必必须加以注注释。对数数据结构的的注释应放放在其上方方相邻位置置，不可放放在下面；对结构中中的每个域域的注释放放在此域的的右方。示例：可按按如下形式式说明枚举举/数据/联合结构构。/* scccp iinterrfacee witth scccp uuser primmitivve meessagge naame */enum SCCCP_USSER_PPRIMIITIVEE NN_UNIITDATTA_INND, /* scccp nnotiffy scccp uuser unitt datta coome */ NN_NOTTICE_IND, /* scccp nnotiffy usser tthe NNo.7 netwwork can not */ /* trransmmissiion tthis messsage */ NN_UNIITDATTA_REEQ, /* scccp uuser''s unnit ddata trannsmisssionn reqquestt*/;¹ 2-11：全局变量量要有较详详细的注释释，包括对对其功能、取取值范围、哪哪些函数或或过程存取取它以及存存取时注意意事项等的的说明。示例：/* Thhe ErrrorCCode whenn SCCCP trransllate */* Glloball Tittle ffailuure, as ffolloows */ / 变量量作用、含含义/* 0 SUCCCESSS 11 GT Tablle errror */* 2 GT erroor OOtherrs no use */ / 变量取取值范围/* onnly funcctionn SCCCPTrransllate() inn */* thhis mmoduaal caan moodifyy it, annd ootherr */* moodulee cann vissit iit thhrouggh caall */* thhe ffuncttion GetGGTTraansErrrorCCode() */ / 使使用方法BYTE g_GTTTrannErroorCodde; ¹ 2-12：注释与所所描述内容容进行同样样的缩排。说明：可使使程序排版版整齐，并并方便注释释的阅读与与理解。示例：如下下例子，排排版不整齐齐，阅读稍稍感不方便便。void exammple_fun( voiid )/* coode oone ccommeents */ CCodeBBlockk Onee /* coode ttwo ccommeents */ CCodeBBlockk Twoo应改为如下下布局。void exammple_fun( voiid ) /* coode oone ccommeents */ CCodeBBlockk Onee /* coode ttwo ccommeents */ CCodeBBlockk Twoo¹ 2-13：将注释与与其上面的的代码用空空行隔开。示例：如下下例子，显显得代码过过于紧凑。/* coode oone ccommeents */progrram ccode one/* coode ttwo ccommeents */progrram ccode two应如下书写写/* coode oone ccommeents */progrram ccode one/* coode ttwo ccommeents */progrram ccode two¹ 2-14：对变量的的定义和分分支语句（条条件分支、循循环语句等等）必须编编写注释。说明：这些些语句往往往是程序实实现某一特特定功能的的关键，对对于维护人人员来说，良良好的注释释帮助更好好的理解程程序，有时时甚至优于于看设计文文档。¹ 2-15：对于swwitchh语句下的的casee语句，如如果因为特特殊情况需需要处理完完一个caase后进进入下一个个casee处理，必必须在该ccase语语句处理完完、下一个个casee语句前加加上明确的的注释。说明：这样样比较清楚楚程序编写写者的意图图，有效防防止无故遗遗漏breeak语句句。示例（注意意斜体加粗粗部分）：case CMD_UP: PProceessUpp(); bbreakk;case CMD_DOWNN: PProceessDoown(); bbreakk;case CMD_FWD: PProceessFwwd(); if (.) . bbreakk;else PProceessCFFW_B(); / now jumpp intto caase CCMD_AAcase CMD_A: PProceessA(); bbreakk;case CMD_B: PProceessB(); bbreakk;case CMD_C: PProceessC(); brreak;case CMD_D: PProceessD(); bbreakk;.½ 2-1：避避免在一行行代码或表表达式的中中间插入注注释。说明：除非非必要，不不应在代码码或表达中中间插入注注释，否则则容易使代代码可理解解性变差。½ 2-2：通通过对函数数或过程、变变量、结构构等正确的的命名以及及合理地组组织代码的的结构，使使代码成为为自注释的的。说明：清晰晰准确的函函数、变量量等的命名名，可增加加代码可读读性，并减减少不必要要的注释。½ 2-3：在在代码的功功能、意图图层次上进进行注释，提提供有用、额额外的信息息。说明：注释释的目的是是解释代码码的目的、功功能和采用用的方法，提提供代码以以外的信息息，帮助读读者理解代代码，防止止没必要的的重复注释释信息。示例：如下下注释意义义不大。/* iff recceivee_flaag iss TRUUE */if (rreceiive_fflag)而如下的注注释则给出出了额外有有用的信息息。 /* iff mtpp recceivee a mmessaage ffrom linkks */if (rreceiive_fflag)½ 2-4：在在程序块的的结束行右右方加注释释标记，以以表明某程程序块的结结束。说明：当代代码段较长长，特别是是多重嵌套套时，这样样做可以使使代码更清清晰，更便便于阅读。示例：参见见如下例子子。if (.) / prrograam coode wwhilee (inndex < MAAX_INNDEX) / prrograam coode /* end of wwhilee (inndex < MAAX_INNDEX) */ / 指指明该条wwhilee语句结束束 /* end of if (.)*/ / 指明明是哪条iif语句结结束½ 2-5：注注释格式尽尽量统一，建建议使用“/* */”。½ 2-6：注注释应考虑虑程序易读读及外观排排版的因素素，使用的的语言若是是中、英兼兼有的，建建议多使用用中文，除除非能用非非常流利准准确的英文文表达。说明：注释释语言不统统一，影响响程序易读读性和外观观排版，出出于对维护护人员的考考虑，建议议使用中文文。3 标识符符命名¹ 3-1：标标识符的命命名要清晰晰、明了，有有明确含义义，同时使使用完整的的单词或大大家基本可可以理解的的缩写，避避免使人产产生误解。说明：较短短的单词可可通过去掉掉“元音”形成缩写写；较长的的单词可取取单词的头头几个字母母形成缩写写；一些单单词有大家家公认的缩缩写。示例：如下下单词的缩缩写能够被被大家基本本认可。temp 可缩写为为 tmmp ;flag 可缩写为为 fllg ;statiisticc 可缩写写为 sstat ;increementt 可缩写写为 iinc ;messaage 可可缩写为 msgg ;¹ 3-2：命命名中若使使用特殊约约定或缩写写，则要有有注释说明明。说明：应该该在源文件件的开始之之处，对文文件中所使使用的缩写写或约定，特特别是特殊殊的缩写，进进行必要的的注释说明明。¹ 3-3：自自己特有的的命名风格格，要自始始至终保持持一致，不不可来回变变化。说明：个人人的命名风风格，在符符合所在项项目组或产产品组的命命名规则的的前提下，才才可使用。（即即命名规则则中没有规规定到的地地方才可有有个人命名名风格）。¹ 3-4：对对于变量命命名，禁止止取单个字字符（如ii、j、k.），建议议除了要有有具体含义义外，还能能表明其变变量类型、数数据类型等等，但i、j、k作局部循循环变量是是允许的。说明：变量量，尤其是是局部变量量，如果用用单个字符符表示，很很容易敲错错（如i写成j），而编编译时又检检查不出来来，有可能能为了这个个小小的错错误而花费费大量的查查错时间。示例：下面面所示的局局部变量名名的定义方方法可以借借鉴。int lliv_WWidthh其变量名解解释如下：l 局部变量量（Loccal） （其它它：g 全局局变量（GGlobaal）.）i 数据类型型（Inttergeer）v 变量（Vaariabble） （其其它：c 常常量（Coonst）.）Widdth 变量含义义这样可以防防止局部变变量与全局局变量重名名。¹ 3-5：命命名规范必必须与所使使用的系统统风格保持持一致，并并在同一项项目中统一一，比如采采用UNIIX的全小小写加下划划线的风格格或大小写写混排的方方式，不要要使用大小小写与下划划线混排的的方式，用用作特殊标标识如标识识成员变量量或全局变变量的m_和g_，其后后加上大小小写混排的的方式是允允许的。示例： AAdd_UUser不不允许，aadd_uuser、AddUUser、m_AdddUseer允许。 ½ 3-1：除除非必要，不不要用数字字或较奇怪怪的字符来来定义标识识符。示例：如下下命名，使使人产生疑疑惑。#defiine _EXAMMPLE_0_TEEST_#defiine _EXAMMPLE_1_TEEST_void set_sls000( BBYTE sls );应改为有意意义的单词词命名#defiine _EXAMMPLE_UNITT_TESST_#defiine _EXAMMPLE_ASSEERT_TTEST_void set_udt_msg_sls( BYTTE slls );½ 3-2：在在同一软件件产品内，应应规划好接接口部分标标识符（变变量、结构构、函数及及常量）的的命名，防防止编译、链链接时产生生冲突。说明：对接接口部分的的标识符应应该有更严严格限制，防防止冲突。如如可规定接接口部分的的变量与常常量之前加加上“模块”标识等。½ 3-3：用用正确的反反义词组命命名具有互互斥意义的的变量或相相反动作的的函数等。说明：下面面是一些在在软件中常常用的反义义词组。add / remmove beegin / ennd creeate / deestrooy inserrt / deleete fiirst / laast gett / rreleaaseincreementt / ddecreementt putt / ggetadd / dellete loock / unllock opeen / clossemin / maxx olld / new staart / stoopnext / prrevioous soourcee / ttargeet shoow / hideesend / reeceivve soourcee / ddestiinatiioncut / passte upp / ddown示例：int min_sum;int max_sum;int add_userr( BYYTE *userr_namme );int deleete_uuser( BYTTE *uuser_namee );½ 3-4：除除了编译开开关/头文件等等特殊应用用，应避免免使用_EEXAMPPLE_TTEST_之类以下下划线开始始和结尾的的定义。 4 可读性性¹ 4-1：注注意运算符符的优先级级，并用括括号明确表表达式的操操作顺序，避避免使用默默认优先级级。说明：防止止阅读程序序时产生误误解，防止止因默认的的优先级与与设计思想想不符而导导致程序出出错。示例：下列列语句中的的表达式word = (hhigh << 88) | low (1)if (a | b) &&& (aa & cc) (2)if (a | b) << (c & d) (3)如果书写为为high << 88 | llowa | bb && a & ca | bb < cc & dd由于high << 88 | llow = ( hhigh << 88) | low,a | bb && a & c = (a | b) && (a & c)，(1)(22)不会出出错，但语语句不易理理解；a | bb < cc & dd = aa | （b < c） & dd，(3)造成成了判断条条件出错。¹ 4-2：避避免使用不不易理解的的数字，用用有意义的的标识来替替代。涉及及物理状态态或者含有有物理意义义的常量，不不应直接使使用数字，必必须用有意意义的枚举举或宏来代代替。示例：如下下的程序可可读性差。if (TTrunkkinddex.trunnk_sttate = 00) TTrunkkinddex.trunnk_sttate = 1; . / pprogrram ccode应改为如下下形式。#defiine TTRUNKK_IDLLE 0#defiine TTRUNKK_