程序编程规范.docx
- 文档编号:14500173
- 上传时间:2023-06-24
- 格式:DOCX
- 页数:21
- 大小:24.14KB
程序编程规范.docx
《程序编程规范.docx》由会员分享,可在线阅读,更多相关《程序编程规范.docx(21页珍藏版)》请在冰点文库上搜索。
程序编程规范
磁力仪程序的编程规范
1:
排版
2:
注释
3:
标识符命名
4:
可读性
5:
变量、结构
6:
函数、过程
7:
程序效率
8:
代码测试、维护
1排版
1-1:
程序块要采用缩进风格编写,缩进的空格数为4个。
相对独立的程序块之间、变量说明之后必须加空行。
示例:
应如下书写
if(!
key)
{
...//programcode
}
//空格
programcode
1-2:
不允许把多个短语句写在一行中,即一行只写一条语句。
示例:
如下例子不符合规范。
i=0;j=0;
应如下书写
i=0;
j=0;
1-3:
if、for、do、while、case、switch、default等语句自占一行,且if、for、do、while
等语句的执行语句部分无论多少都要加括号{}。
示例:
如下例子不符合规范。
if(i==0)return;
应如下书写:
if(i==0)
{
return;
}
1-4:
函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格,case
语句下的情况处理语句也要遵从语句缩进要求。
1-5:
程序块的分界符(如C/C++语言的大括号‘{’和‘}’)应各独占一行并且位于同一列,
同时与引用它们的语句左对齐。
在函数体的开始、类的定义、结构的定义、枚举的定义以
及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例:
如下例子不符合规范。
for(...){
...//programcode
}
应如下书写。
for(...)
{
...//programcode
}
1-6:
一行程序以小于80字符为宜,不要写得过长。
2注释
2-1:
一般情况下,源程序有效注释量必须在20%以上。
说明:
注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能
太少,注释语言必须准确、易懂、简洁。
2-2:
文件头部应进行注释,注释必须列出:
版权说明、版本号、生成日期、作者、内容、
功能、修改日志等。
示例:
下面这段头文件的头注释比较标准。
/*****************************************************************************
Copyright:
2012-2013,jlu,447
Filename:
文件名
Description:
用于详细说明此程序文件完成的主要功能,与其他模块或函数的接口,输出
值、取值范围、含义及参数间的控制、顺序、独立或依赖等关系
Author:
作者
Version:
版本
Date:
完成日期
History:
修改历史记录列表,每条修改记录应包括修改日期、修改
者及修改内容简述。
*****************************************************************************/
2-3:
函数头部应进行注释,列出:
函数的目的/功能、输入参数、输出参数、返回值、调用
关系(函数、表)等。
示例:
下面这段函数的注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在
内。
/*************************************************
Function:
//函数名称
Description:
//函数功能、性能等的描述
Calls:
//被本函数调用的函数清单
CalledBy:
//调用本函数的函数清单
Input:
//输入参数说明,包括每个参数的作
//用、取值说明及参数间关系。
Output:
//对输出参数的说明。
Return:
//函数返回值的说明
Others:
//其它说明
*************************************************/
2-4:
边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
不再
有用的注释要删除。
2-5:
注释的内容要清楚、明了,含义准确,防止注释二义性。
说明:
错误的注释不但无益反而有害。
2-6:
注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)
相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
应如下书写
programcode
//空格隔开
/*注释*/
programcode
2-7:
对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须
加以注释,说明其物理含义。
变量、常量的注释应放在其上方相邻位置或右方。
示例:
/*activestatistictasknumber*/
#defineMAX_NUMBER1000
#defineMAX_NUMBER1000/*activestatistictasknumber*/
2-8:
局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及
存取时注意事项等的说明。
示例:
2-9:
注释与所描述内容进行同样的缩排。
说明:
可使程序排版整齐,并方便注释的阅读与理解。
voidexample_fun(void)
{
/*codeonecomments*/
CodeBlockOne
/*codetwocomments*/
CodeBlockTwo
}
2-10:
避免一行代码或表达式的中间插入注释。
说明:
除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
2-12:
通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成
为自注释的。
说明:
清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
2-13:
在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说明:
注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者
理解代码,防止没必要的重复注释信息。
示例:
如下注释意义不大。
/*ifreceive_flagisTRUE*/
if(receive_flag)
2-14:
在程序块的结束行右方加注释标记,以表明某程序块的结束。
说明:
当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
示例:
参见如下例子。
if(...)
{
//programcode
while(index { //programcode }/*endofwhile(index }/*endofif(...)*///指明是哪条if语句结束 2-15: 注释格式尽量统一,建议使用“/*⋯⋯*/”。 2-16: 注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用 中文,除非能用非常流利准确的英文表达。 说明: 注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中 文。 3标识符命名 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: 命名规范必须与所使用的系统风格保持一致,并在同一项目中统一的全小写加下划线的风格或大小写混排的方式,不要使用大小写与下划线混排的方式 3-6: 除非必要,不要用数字或较奇怪的字符来定义标识符。 示例: 如下命名,使人产生疑惑。 #define_EXAMPLE_0_TEST_ #define_EXAMPLE_1_TEST_ 应改为有意义的单词命名 #define_EXAMPLE_UNIT_TEST_ #define_EXAMPLE_ASSERT_TEST_ 3-7: 在同一软件产品内,应规划好接口部分标识符(变量、结构、函数及常量)的命名, 防止编译、链接时产生冲突。 说明: 对接口部分的标识符应该有更严格限制,防止冲突。 如可规定接口部分的变量与常量 之前加上“模块”标识等。 3-8: 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。 说明: 下面是一些在软件中常用的反义词组。 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; 4可读性 4-1: 注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。 说明: 防止阅读程序时产生误解,防止因默认的优先级与设计思想不符而导致程序出错。 示例: word=(high<<8)|low (1) if((a|b)&&(a&c)) (2) if((a|b)<(c&d))(3) 4-2: 避免使用不易理解的数字,用有意义的标识来替代。 涉及物理状态或者含有物理意义 的常量,不应直接使用数字,必须用有意义的枚举或宏来代替。 示例: 如下的程序可读性差。 if(trunk_state==0) { trunk_state=1; ...//programcode; } 应改为如下形式。 #defineTRUNK_IDLE0 #defineTRUNK_BUSY1 if(trunk_state==TRUNK_IDLE) { trunk_state=TRUNK_BUSY; ...//programcode } 4-3: 源程序中关系较为紧密的代码应尽可能相邻。 说明: 便于程序阅读和查找。 示例: 以下代码布局不太合理。 rect.length=10; char_poi=str; rect.width=5; 若按如下形式书写,可能更清晰一些。 rect.length=10; rect.width=5;//矩形的长与宽关系较密切,放在一起。 char_poi=str; 4-4: 不要使用难懂的技巧性很高的语句,除非很有必要时。 说明: 高技巧语句不等于高效率的程序,实际上程序的效率关键在于算法。 5变量、结构 5-1: 去掉没必要的公共变量。 说明: 公共变量是增大模块间耦合的原因之一,故应减少没必要的公共变量以降低模块间的 耦合度。 5-2: 仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系。 说明: 在对变量声明的同时,应对其含义、作用及取值范围进行注释说明,同时若有必要还 应说明与其它变量的关系。 5-3: 明确公共变量与操作此公共变量的函数或过程的关系,如访问、修改及创建等。 5-4: 当向公共变量传递数据时,要十分小心,防止赋与不合理的值或越界等现象发生。 说明: 对公共变量赋值时,若有必要应进行合法性检查,以提高代码的可靠性、稳定性。 5-5: 防止局部变量与公共变量同名。 说明: 若使用了较好的命名规则,那么此问题可自动消除。 5-6: 严禁使用未经初始化的变量作为右值。 5-7: 仔细设计结构中元素的布局与排列顺序,使结构容易理解、节省占用空间,并减少引 起误用现象。 说明: 合理排列结构中元素顺序,可节省空间并增加可理解性。 5-8: 编程时,要注意数据类型的强制转换。 说明: 当进行数据类型强制转换时,其数据的意义、转换后的取值等都有可能发生变化,而 这些细节若考虑不周,就很有可能留下隐患。 5-9: 尽量减少没有必要的数据类型默认转换与强制转换。 5-10: 合理地设计数据并使用自定义数据类型,避免数据间进行不必要的类型转换。 6函数、过程 6-1: 对所调用函数的错误返回码要仔细、全面地处理。 6-2: 明确函数功能,精确(而不是近似)地实现函数设计。 6-3: 函数的规模尽量限制在200行以内。 说明: 不包括注释和空格行。 6-4: 一个函数仅完成一件功能,不要设计多用途面面俱到的函数。 说明: 多功能集于一身的函数,很可能使函数的理解、测试、维护等变得困难。 6-5: 函数的功能应该是可以预测的,也就是只要输入数据相同就应产生同样的输出。 6-6: 尽量不要编写依赖于其他函数内部实现的函数。 说明: 此条为函数独立性的基本要求。 由于目前大部分高级语言都是结构化的,所以通过具 体语言的语法要求与编译器功能,基本就可以防止这种情况发生。 但在汇编语言中,由于其 灵活性,很可能使函数出现这种情况 。 6-7: 检查函数所有参数输入的有效性。 6-8: 检查函数所有非参数输入的有效性,公共变量等。 说明: 函数的输入主要有两种: 一种是参数输入;另一种是全局变量,即 非参数输入。 函数在使用输入之前,应进行必要的检查。 6-9: 函数名应准确描述函数的功能。 6-10: 使用动宾词组为执行某操作的函数命名。 可以只有动词(名词是 对象本身)。 示例: 参照如下方式命名函数。 voidprint_record(unsignedintrec_ind); intinput_record(void); unsignedcharget_current_color(void); 6-11: 避免使用无意义或含义不清的动词为函数命名。 说明: 避免用含义不清的动词如process、handle等为函数命名,因为这些动词并没有说明 要具体做什么。 6-12: 函数的返回值要清楚、明了,让使用者不容易忽视错误情况。 说明: 函数的每种出错返回值的意义要清晰、明了、准确,防止使用者误用、理解错误或忽 视错误返回码。 6-13: 除非必要,最好不要把与函数返回值类型不同的变量,以编译系统默认的转换方式或 强制的转换方式作为返回值返回。 6-14: 让函数在调用点显得易懂、容易理解。 6-15: 在调用函数填写参数时,应尽量减少没有必要的默认数据类型转换或强制数据类型转 换。 说明: 因为数据类型转换或多或少存在危险。 6-16: 避免函数中不必要语句,防止程序中的垃圾代码。 说明: 程序中的垃圾代码不仅占用额外的空间,而且还常常影响程序的功能与性能,很可能 给程序的测试、维护等造成不必要的麻烦。 6-17: 防止把没有关联的语句放到一个函数中。 6-18: 功能不明确较小的函数,特别是仅有一个上级函数调用它时,应考虑把它合并到上级 函数中,而不必单独存在。 说明: 模块中函数划分的过多,一般会使函数间的接口变得复杂。 所以过小的函数,特别是 扇入很低的或功能不明确的函数,不值得单独存在。 6-19: 减少函数本身或函数间的递归调用。 说明: 递归调用特别是函数间的递归调用(如A->B->C->A),影响程序的可理解性;递归 调用一般都占用较多的系统资源(如栈空间);递归调用对程序的测试有一定影响。 故除非 为某些算法或功能的实现方便,应减少没必要的递归调用。 6-20: 改进模块中函数的结构,降低函数间的耦合度,并提高函数的独立性以及代码可读性、 效率和可维护性。 优化函数结构时,要遵守以下原则: (1)不能影响模块功能的实现。 (2)仔细考查模块或函数出错处理及模块的性能要求并进行完善。 (3)通过分解或合并函数来改进软件结构。 (4)考查函数的规模,过大的要进行分解。 (5)降低函数间接口的复杂度。 (6)不同层次的函数调用要有较合理的扇入、扇出。 (7)函数功能应可预测。 (8)提高函数内聚。 (单一功能的函数内聚最高) 说明: 对初步划分后的函数结构应进行改进、优化,使之更为合理。 6-21: 对于提供了返回值的函数,在引用时最好使用其返回值。 6-22: 当一个过程(函数)中对较长变量(一般是结构的成员)有较多引用时,可以用一个 意义相当的宏代替。 说明: 这样可以增加编程效率和程序的可读性。 示例: 在某过程中较多引用TheReceiveBuffer[FirstSocket].byDataPtr, 则可以通过以下宏定义来代替: #definepSOCKDATATheReceiveBuffer[FirstScoket].byDataPtr 7程序效率 7-1: 编程时要经常注意代码的效率。 说明: 代码效率分为全局效率、局部效率、时间效率及空间效率。 全局效率是站在整个系统 的角度上的系统效率;局部效率是站在模块或函数角度上的效率;时间效率是程序处理输入 任务所需的时间长短;空间效率是程序所需内存空间,如机器代码空间大小、数据空间大小、 栈空间大小等。 7-2: 在保证软件系统的正确性、稳定性、可读性及可测性的前提下,提高代码效率。 说明: 不能一味地追求代码效率,而对软件的正确性、稳定性、可读性及可测性造成影响。 7-3: 局部效率应为全局效率服务,不能因为提高局部效率而对全局效率造成影响。 7-4: 循环体内工作量最小化。 说明: 应仔细考虑循环体内的语句是否可以放在循环体之外,使循环体内工作量最小,从而 提高程序的时间效率。 示例: 如下代码效率不高。 for(ind=0;ind { sum+=ind; back_sum=sum; } 语句“back_sum=sum;”完全可以放在for语句之后,如下。 for(ind=0;ind { sum+=ind; } back_sum=sum; 7-5: 仔细分析有关算法,并进行优化。 仔细考查、分析系统及模块处理输入 7-6: 对模块中函数的划分及组织方式进行分析、优化,改进模块中函数的组织结构,提高 程序效率。 说明: 软件系统的效率主要与算法、处理任务方式、系统功能及函数结构有很大关系,仅在 代码上下功夫一般不能解决根本问题。 7-7: 编程时,要随时留心代码效率;优化代码时,要考虑周全。 7-8: 不应花过多的时间拼命地提高调用不很频繁的函数代码效率。 说明: 对代码优化可提高效率,但若考虑不周很有可能引起严重后果。 7-9: 在保证程序质量的前提下,通过压缩代码量、去掉不必要代码以及减少不必要的局部 和全局变量,来提高空间效率。 说明: 这种方式对提高空间效率可起到一定作用,但往往不能解决根本问题。 7-10: 在多重循环中,应将最忙的循环放在最内层。 说明: 减少CPU切入循环层的次数。 示例: 如下代码效率不高。 for(row=0;row<100;row++) { for(col=0;col<5;col++) { sum+=a[row][col]; } } 可以改为如下方式,以提高效率。 for(col=0;col<5;col++) { for(row=0;row<100;row++) { sum+=a[row][col]; } } 7-11: 尽量减少循环嵌套层次。 7-12: 避免循环体内含判断语句,应将循环语句置于判断语句的代码块之中。 说明: 目的是减少判断次数。 循环体中的判断语句是否可以移到循环体外,要视程序的具体 情况而言,一般情况,与循环变量无关的判断语句可以移到循环体外,而有关的则不可以。 示例: 如下代码效率稍低。 for(ind=0;ind { if(data_type==RECT_AREA) { area_sum+=rect_area[ind]; } else { rect_length_sum+=rect[ind].length; rect_width_sum+=rect[ind].width; } } 因为判断语句与循环变量无关,故可如下改进,以减少判断次数。 if(data_type==RECT_AREA) { for(ind=0;ind { area_sum+=rect_area[ind]; } } else { for(ind=0;ind { rect_length_sum+=rect[ind].length; rect_width_sum+=rect[ind].width; } } 7-13: 尽量用乘法或其它方法代替除法,特别是浮点运算中的除法。 说明: 浮点运算除法要占用较多CPU资源。 示例: 如下表达式运算可能要占较多CPU资源。 #definePAI3.1416 radius=circle_length/(2*PAI); 应如下把浮点除法改为浮点乘法。 #definePAI_RECIPROCAL(1/3.1416)//编译器编译时,将生成具体浮点数 radius=circle_length*PAI_RECIPROCAL/2; 8代码测试、维护 8-1: 正式版本上软件的任何修改都
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 程序 编程 规范