编程规范.docx
- 文档编号:14099780
- 上传时间:2023-06-20
- 格式:DOCX
- 页数:37
- 大小:37.04KB
编程规范.docx
《编程规范.docx》由会员分享,可在线阅读,更多相关《编程规范.docx(37页珍藏版)》请在冰点文库上搜索。
编程规范
北京康吉森交通技术有限公司
——C/C++语言的编程规范
目录
一、排版2
二、注释5
三、标识符命名9
四、可读性11
五、变量12
六、函数、过程14
七、可测性18
八、程序效率20
九、质量保证23
十、代码编辑、编译、审查27
十一、宏27
一、排版
1.1
程序块要采用缩进风格编写,根据层级关系进行缩进,下一级相对上一级缩进4个空格。
开发环境自动生成的代码除外。
1.2
相对独立的程序块之间、变量说明之后必须加空行。
例:
inta;
intb;
a=1;
1.3
较长的语句(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。
例:
act_task_table[taskno].duration_true_or_false
=SYS_get_sccp_statistic_state(stat_item);
report_or_not_flag=((taskno &&(n7stat_stat_item_valid(stat_item)) &&(act_task_table[taskno].result_data! =0)); 1.4 循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在新行之首。 例: if((taskno &&(n7stat_stat_item_valid(stat_item))) { ...//programcode } 1.5 若函数或过程中的参数较长,则要进行适当的划分。 例: n7stat_str_compare((BYTE*)&stat_object, (BYTE*)&(act_task_table[taskno].stat_object), sizeof(_STAT_OBJECT)); 1.6 不允许把多个短语句写在一行中,即一行只写一条语句。 例: a=0; b=0; 不允许: a=0;b=0; 1.7 if、while、for、default、do等语句自占一行。 例: if(pSection==NULL) { return; } 不允许: if(pSection==NULL)return; 1.8 对齐只使用TAB键,不使用空格键。 说明: 以免用不同的编辑器阅读程序时,因TAB键所设置的空格数目不同而造成程序布局不整齐。 1.9 函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格,case语句下的情况处理语句也要遵从语句缩进要求。 1.10 程序块的分界符(如C/C++语言的大括号'{'和'}')应各独占一行并且位于同一列,同时与引用它们的语句左对齐。 在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while0、switch、case语句中的程序都要采用如上的缩进方式。 即使只有一个语句也必须遵循该原则。 for(...) { ...//programcode } if(...) { ...//programcode } voidexample_fun(void) { ...//programcode } 1.11 在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如->),后不应加空格。 说明: 采用这种松散方式编写代码的目的是使代码更加清晰。 由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格,多重括号间不必加空格,因为在C/C++语言中括号已经是最清晰的标志了。 在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。 给操作符留空格时不要连续留两个以上空格。 例: (1)逗号、分号只在后面加空格。 inta,b,c; (2)比较操作符,赋值操作符"="、"+=",算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后加空格。 if(current_time>=MAX_TIME_VALUE) a=b+c; a*=2; a=b^2; (3)"! "、"~"、"++"、"--"、"&"(地址运算符)等单目操作符前后不加空格。 *p='a';//内容操作"*"与内容之间 flag=! isEmpty;//非操作"! "与内容之间 p=&mem;//地址操作"&"与内容之间 i++;//"++","--"与内容之间 (4)"->"、"."前后不加空格。 p->id=pid;//"->"指针前后不加空格 (5)if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。 if(a>=b&&c>d) 1.12 程序结构清析,简单易懂,单个函数的程序行数不得超过100行。 二、注释 2.1 一般情况下,源程序有效注释量必须在20%以上。 说明: 注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。 例: 不要写这样的注释: int*p;//定义一个指向整型的指针变量 可写这样的注释: int*p;//p用来临时保存变量x 2.2 说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出: 版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。 例: 下面这段头文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************* Copyright(C),2003-2009,CONSENTech.Co.,Ltd. Filename: //文件名 Author: //Version: Date: //作者、版本及完成日期 Description: //用于详细说明此程序文件完成的主要功能,与其他模块 //或函数的接口,输出值、取值范围、含义及参数间的控 //制、顺序、独立或依赖等关系 Others: //其它内容的说明 FunctionList: //主要函数列表,每条记录应包括函数名及功能简要说明 1..... History: //修改历史记录列表,每条修改记录应包括修改日期、修改 //者及修改内容简述 1.Date: Author: Modification: 2.... *************************************************/ 2.3 源文件头部应进行注释,列出: 版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 例: 下面这段源文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************************ Copyright(C),2003-2009,CONSENTech.Co.,Ltd. FileName: test.cpp Author: Version: Date: Description: //模块描述 Version: //版本信息 FunctionList: //主要函数及其功能 1.------- History: //历史修改记录 David96/10/121.0buildthismoudle ***********************************************************/ 说明: Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。 History是修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述。 2.4 函数头部应进行注释,列出: 函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。 例: 下面这段函数的注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。 /************************************************* Function: //函数名称 Description: //函数功能、性能等的描述 Calls: //被本函数调用的函数清单 CalledBy: //调用本函数的函数清单 TableAccessed: //被访问的表(此项仅对于牵扯到数据库操作的程序) TableUpdated: //被修改的表(此项仅对于牵扯到数据库操作的程序) Input: //输入参数说明,包括每个参数的作 //用、取值说明及参数间关系。 Output: //对输出参数的说明。 Return: //函数返回值的说明 Others: //其它说明 *************************************************/ 2.5 边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。 不再有用的注释要删除。 2.6 注释的内容要清楚、明了,含义准确,防止注释二义性。 2.7 避免在注释中使用缩写,特别是非常用缩写。 2.8 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 例: /*getreplicatesubsystemindexandnetindicator*/ repssn_ind=ssn_data[index].repssn_index; repssn_ni=ssn_data[index].ni; 或: repssn_ind=ssn_data[index].repssn_index;//getreplicatesub repssn_ni=ssn_data[index].ni; 2.9 对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。 变量、常量、宏的注释应放在其上方相邻位置或右方。 /*activestatistictasknumber*/ #defineMAX_ACT_TASK_NUMBER1000 2.10 数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。 对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。 例: 可按如下形式说明枚举/数据/联合结构。 /*sccpinterfacewithsccpuserprimitivemessagename*/ enumSCCP_USER_PRIMITIVE { N_UNITDATA_IND,/*sccpnotifysccpuserunitdatacome*/ N_NOTICE_IND,/*sccpnotifyusertheNo.7networkcannot*/ /*transmissionthismessage*/ N_UNITDATA_REQ,/*sccpuser'sunitdatatransmissionrequest*/ }; 2.11 全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取以及存取时注意事项等的说明。 例: /*TheErrorCodewhenSCCPtranslate*/ /*GlobalTitlefailure,asfollows*///变量作用、含义 /*0-SUCCESS1-GTTableerror*/ /*2-GTerrorOthers-nouse*///变量取值范围 /*onlyfunctionSCCPTranslate()in*/ /*thismodualcanmodifyit,andother*/ /*modulecanvisititthroughcall*/ /*thefunctionGetGTTransErrorCode()*///使用方法 BYTEg_GTTranErrorCode; 2.12 注释与所描述内容进行同样的缩排。 例: voidexample_fun(void) { /*codeonecomments*/ CodeBlockOne /*codetwocomments*/ CodeBlockTwo } 2.13 将注释与其上面的代码用空行隔开。 例: /*codeonecomments*/ programcodeone /*codetwocomments*/ programcodetwo 2.14 对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。 说明: 这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。 2.15 对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。 2.16 当有嵌套时在程序块的结束行右方加注释标记,以表明某程序块的结束。 说明: 当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。 例: if(...) { //programcode while(index { //programcode }/*endofwhile(index }/*endofif(...)*///指明是哪条if语句结束 2.17 多行注释使用“/*……*/”,单行注释使用: ”//” 三、标识符命名 3.1 标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。 说明: 较短的单词可通过去掉“元音”形成缩写;较长的单词可取单词的头几个字母形成缩写;一些单词有大家公认的缩写。 例: temp可缩写为tmp; flag可缩写为flg; statistic可缩写为stat; increment可缩写为inc; message可缩写为msg; 3.2 命名中若使用特殊约定或缩写,则要有注释说明。 3.3 自己特有的命名风格,要自始至终保持一致,不可来回变化。 3.4 对于变量命名,禁止取单个字符(如i、j、k...),建议除了要有具体含义外,还能表明其变量类型、数据类型等,但i、j、k作局部循环变量是允许的。 说明: 变量,尤其是局部变量,如果用单个字符表示,很容易敲错(如i写成j),而编译时又检查不出来,有可能为了这个小小的错误而花费大量的查错时间。 例: 下面所示的局部变量名的定义方法可以借鉴。 intliv_Width 其变量名解释如下: l局部变量(Local)(其它: g全局变量(Global)...) i数据类型(Interger) v变量(Variable)(其它: c常量(Const)...) Width变量含义 这样可以防止局部变量与全局变量重名。 3.5 命名规范必须与所使用的系统风格保持一致,并在同一项目中统一,比如采用UNIX的全小写加下划线的风格或大小写混排的方式,不要使用大小写与下划线混排的方式。 四、可读性 4.1 注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。 说明: 防止阅读程序时产生误解,防止因默认的优先级与设计思想不符而导致程序出错。 例: 下列语句中的表达式 word=(high<<8)|low (1) if((a|b)&&(a&c)) (2) if((a|b)<(c&d))(3) 如果书写为 high<<8|low a|b&&a&c a|b 由于 high<<8|low=(high<<8)|low, a|b&&a&c=(a|b)&&(a&c), (1) (2)不会出错,但语句不易理解; a|b 4.2 避免使用不易理解的数字,用有意义的标识来替代。 涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的枚举或宏来代替。 例: 如下的程序可读性差。 if(Trunk[index].trunk_state==0) { Trunk[index].trunk_state=1; ...//programcode } 应改为如下形式。 #defineTRUNK_IDLE0 #defineTRUNK_BUSY1 if(Trunk[index].trunk_state==TRUNK_IDLE) { Trunk[index].trunk_state=TRUNK_BUSY; ...//programcode } 五、变量 5.1 去掉没必要的公共变量。 说明: 公共变量是增大模块间耦合的原因之一,故应减少没必要的公共变量以降低模块间的耦合度。 5.2 防止局部变量与公共变量同名。 5.3 严禁使用未经初始化的变量作为右值。 右值可以简单理解为=号右边的值. 说明: 特别是在C/C++中引用未经赋值的指针,经常会引起系统崩溃。 5.4 构造仅有一个模块或函数可以修改、创建,而其余有关模块或函数只访问的公共变量,防止多个不同模块或函数都可以修改、创建同一公共变量的现象。 说明: 降低公共变量耦合度。 5.5 使用严格形式定义的、可移植的数据类型,尽量不要使用与具体硬件或软件环境关系密切的变量。 说明: 使用标准的数据类型,有利于程序的移植。 例: 如下例子(在DOS下BC3.1环境中),在移植时可能产生问题。 voidmain() { registerintindex;//寄存器变量 _AX=0x4000;//_AX是BC3.1提供的寄存器“伪变量” ...//programcode } 5.6 数据结构的功能要单一,是针对一种事务的抽象。 不要设计面面俱到、非常灵活的数据结构,面面俱到、灵活的数据结构反而容易引起误解和操作困难。 5.7 结构中元素的个数应适中。 若结构中元素个数过多可考虑依据某种原则把元素组成不同的子结构,以减少原结构中元素的个数。 5.8 仔细设计结构中元素的布局与排列顺序,使结构容易理解、节省占用空间,并减少引起误用现象。 说明: 合理排列结构中元素顺序,可节省空间并增加可理解性。 例: 如下结构中的位域排列,将占较大空间,可读性也稍差。 typedefstructEXAMPLE_STRU { unsignedintvalid: 1; PERSONperson; unsignedintset_flg: 1; }EXAMPLE; 若改成如下形式,不仅可节省1字节空间,可读性也变好了。 typedefstructEXAMPLE_STRU { unsignedintvalid: 1; unsignedintset_flg: 1; PERSONperson; }EXAMPLE; 5.9 对编译系统默认的数据类型转换,也要有充分的认识。 例: 如下赋值,多数编译器不产生告警,但值的含义还是稍有变化。 charchr; unsignedshortintexam; chr=-1; exam=chr;//编译器不产生告警,此时exam为0xFFFF。 5.10 合理地设计数据并使用自定义数据类型,避免数据间进行不必要的类型转换。 对自定义数据类型进行恰当命名,使它成为自描述性的,以提高代码可读性。 注意其命名方式在同一产品中的统一。 说明: 使用自定义类型,可以弥补编程语言提供类型少、信息量不足的缺点,并能使程序清晰、简洁。 例: 可参考如下方式声明自定义数据类型。 下面的声明可使数据类型的使用简洁、明了。 typedefunsignedcharBYTE; typedefunsignedshortWORD; typedefunsignedintDWORD; 下面的声明可使数据类型具有更丰富的含义。 typedeffloatDISTANCE; typedeffloatSCORE; 6-5: 当声明用于分布式环境或不同CPU间通信环境的数据结构时,必须考虑机器的字节顺序、使用的位域及字节对齐等问题,即所谓的大端(BigEndian)模式和小端(LittleEndian)模式。 一般Intel的CPU工作在小端模式,Motorola的CPU工作在大端模式,有些CPU如ARM既可工作在大端,又可工作在小端。 六、函数、过程 6.1 编写可重入函数时,应注意局部变量的使用(如编写C/C++语言的可重入函数时,应使用auto即缺省态局部变量或寄存器变量)。 说明: 在可重入性函数中,不一般不能有static、全局变量等,除非经过特殊处理。 6.2 编写可重入函数时,若使用全局变量,则应通过关中断、信号量(即P、V操作)等手段对其加以保护。 说明: 若对所使用的全局变量不加以保护,则此函数就不具有可重入性,即当多个进程调用此函数时,很有可能使有关全局变量变为不可知状态。 例: 假设Exam是int型全局变量,函数Squre_Exam返回Exam平方值。 那么如下函数不具有可重入性。 unsignedintexample(intpara) { unsignedinttemp; Exam=para;//(**) temp=Square_Exam(); return
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 编程 规范