软件开发编程规范.docx
- 文档编号:10330670
- 上传时间:2023-02-10
- 格式:DOCX
- 页数:14
- 大小:21.84KB
软件开发编程规范.docx
《软件开发编程规范.docx》由会员分享,可在线阅读,更多相关《软件开发编程规范.docx(14页珍藏版)》请在冰豆网上搜索。
软件开发编程规范
软
件
编
程
规
范
目录
前言2
1.编程风格2
2.适用范围2
3.注释规范3
3.1注释原则3
3.2文件注释3
3.3函数注释4
3.4变量注释4
3.5代码注释5
4.命名规则5
4.1命名原则5
4.2命名定义6
5.代码风格8
5.1代码书写原则8
5.2对齐和缩进8
5.3空格的使用8
5.4括号的使用9
5.5空行的使用9
5.6头文件引用9
5.7代码发布原则10
6.代码示例对比10
6.1代码行书写10
6.2代码对齐11
前言
本文档提出了部门内软件开发人员在开发过程中应当遵循的编程规范,以便规范开发人员养成良好的编程习惯,提高代码的书写质量,增强其可读性、可维护性、健壮性、可移植性、可交流性。
特别声明,限于编写者水平和经验,本文的内容需要大家的补充、建议、帮助来完善,在实践中提高可操作性。
因此,本文内容只作为指导性建议,而不是最终的强制性标准。
本规范旨在抛砖引玉,希望大家能够把自己的宝贵经验拿出来一起分享,共同进步,共同提高我们的编码质量。
1.编程风格
所谓编程风格实际上就是编程习惯,它包含两个层次的概念:
编码格式和语言运用。
本规范所涉及的主要是编码格式的有关范畴:
注释规范、命名规则、代码风格;文中所写格式以C/C++语言编程习惯为范例。
好的编程风格,必须具备清楚的注释、良好的命名习惯;没有注释、变量随意命名,是编程之大忌,这样写出的代码,行数多了以后有时甚至连编程人员自己都无法看懂,可读性无所谈起。
实际编程中,常常会因使用的语言、开发工具、操作系统不同而编码风格会有所不同,我们应尽量保持与开发语言、工具的风格相一致,同时也要保持自己既定的风格。
有了自己既定风格的编码,当代码在不同的语言或不同的操作系统平台移值时,可读性强,易于理解。
2.适用范围
本文的规范在原则上适用于C、C++的编写,使用其它编程语言(如Java、Delphi、VB等)时仅供参考。
3.注释规范
3.1注释原则
1>、尽量使用中文注释,以便于理解,防止歧义性。
2>、在保证意思表达清楚的基础上,尽可能简洁,节约书写和阅读的时间。
3>、尽可能语义完整、清晰,书写工整、对齐。
4>、在编码的过程中,及时注释,特别是一些关键算法或重要操作处,修改代码同时修改注释,保证代码和注释一致。
5>、注释中最好包括作者和日期,特别是在修改他人代码的时候。
6>、注释要写在被注释代码的上方或右侧,不得写在下方。
7>、添加注释以有利于理解代码为原则,有必要之处才添加,注释不是文档,过多或过少均不可取。
8>、注释符的使用,整段注释用“/*”和“*/”包括;单行注释使用“//”。
3.2文件注释
开发人员自己创建的文件(开发工具自动生成除外),在头文件和实现文件中都应写上文件注释,格式如下:
/*
---------------------------------------------------------------------------------
版权声明:
版权所有、开发起止年份、公司名称、权利保留
文件名:
作者:
版本号:
创建日期:
描述说明:
--------------------------------------------------------------------------------
*/
示例:
/*
-----------------------------------------------------------------------------
Copyright(C),2001-2008,ShenZhenJLNitsLtd.AllRightsReserved
Filename:
VideoCaptureCtrl.h
Author:
张晏斌
Version:
0.1
Date:
2008.5.22
Description:
视频采集封装头文件。
-----------------------------------------------------------------------------
*/
3.3函数注释
在函数定义声明开头(通常写在头文件中),应有如下注释:
/********************************************************************/
/*函数名称:
/*函数功能:
/*参数说明:
参数1代表涵义
/*参数2代表涵义
/*
/*返回值:
/*调用说明:
(可选项,视函数情况按需而定)
/********************************************************************/
示例:
/********************************************************************/
/*函数名称:
GetTargetFrameImg(intiPort,intiPos)
/*功能:
抓取目标位置帧图像
/*参数说明:
iPort端口号
/*iPos抓帧位置取值范围<=00表示当前位置
/*返回值:
0取图失败;>0返回图像地址(HBITMAP)
/*调用说明:
调用本函数后取出的图像由调用层负责释放
/********************************************************************/
在实现文件(.cpp)中,为减少书写的繁琐,每个函数实现定义前,可不必再作如上注释说明,但必须在函数顶部用单行注释写上该函数功能说明。
在函数体内,必要的代码前也应写上相应的一些注释,具体可视情况而定。
3.4变量注释
对于自定义的一些重要变量(含全局变量、实例变量、类成员变量、局部变量等),在定义时要加以注释,尽可能说明其用途、作用域、可能值的变化范围等;变量定义的声明,尽可能集中放在文件或函数的顶部,尽量减少在代码行中间随意定义;通用变量的定义可视情况而定,但要尽量遵循上述定义规则,保证书写的工整性、可读性。
注:
通用变量泛指大家约定俗成习惯使用的变量,如循环控制变量(i,j)等。
3.5代码注释
1>、重要变量赋值时,应当加以注释说明。
2>、代码逻辑控制流程、用于流程控制的变量、信号量、事件等必须加注释说明。
3>、代码中完成某一逻辑功能的代码段,须加以注释说明。
4>、程序代码中调用子函数之前,应加注调用该函数作用的注释说明;除非被调用子函数从名称上可明确识别其用途,则可不加注释。
4.命名规则
4.1命名原则
1>、使用英文单词组合,对于过长的单词,可以按业界编程习惯简写,禁用汉语拼音命名;英文单词组合时,单词首字母大写和单词体小写相结合,力求能清晰区分单词,字符串美观整洁。
2>、力求清晰表达其涵义及内容,用词简单,让人一目了然,见文知意。
3>、增加必要前缀,防止命名冲突,便于阅读理解、区分。
4>、命名时尽量以最小的长度,表达最多的意思。
5>、功能函数的名称尽量使用动词+名词的组合形式。
例如:
显示视频voidShowVideo()。
6>、变量名称尽量采用能清楚表达其意义的名词或形容词+名词组合形式。
例如:
当前帧索引iCurrentFrameIndex。
7>、常量名、宏定义使用大写字母、大写字母+下滑线、单词首字母大写形式定义,首选全部用大字字母。
例如:
MAXCHNO、MAX_CHNO、Max_Chno。
4.2命名定义
1>、宏定义和常量:
宏定义和常量的声明都集中放在头文件或实现文件的顶部区域,且每个定义都标上注释,其命名方法遵循4.1命名原则。
在编码的过程中,对于一些可变的最大、最小值,多次调用的数组下标的定义,统一都采用宏定义的形式声明,尽量避免在代码中出现绝对数字值。
如:
声明一个全局的图像序列数组HBITMAPg_hImgSequence[MAX_IMAGE];不良声明方法HBITMAPg_hImgSequence[20];
2>、变量命名格式:
a.局部变量:
Local首字母+变量类型首字母_变量名组合形式命名。
如:
局部整型计数变量li_count;字符串变量:
ls_fileName。
b.类成员变量:
数值成员变量命名格式,m_类型首字母+名称,如m_iCount;
对话框类中控件对应成员变量命名格式,m_控件类型缩写+名称,如按钮:
m_btnXXX;列表框:
m_listXXX;编辑框:
m_edXXX;下拉列表:
m_cmbXXX;CheckBox:
m_ckXXX;RadioButton:
m_rdXXX等。
c.静态变量:
s_类型首字+名称。
如:
s_iCount。
d.全局变量:
g_类型首字+名称。
如:
g_iCount。
3>、结构体类型定义:
在程序编码中,需要使用结构体时,都以结构体类型定义的形式进行声明,如果程序中需大量使用结构定义,则可单独建立头文件,将结构体的定义全部集中在一个头文件中,便于代码修改维护。
定义格式如下:
typedefstruct
{
类型成员1;
类型成员2;
……
}T+类型名称+Str(注:
首字母T表示是类型定义,Str表示结构)
示例:
//红灯运行数据结构
typedefstruct
{
IntiRedCount;//红灯总时长(秒)
IntiRedRunCount;//红灯运行时长(秒)
}TRedLampCounterStr;
4>、函数命名:
遵循4.1.5命名原则;C++提供了类封装,对于使用C开发的函数定义,可以按模块划分加上前缀进行声明定义,以示区分。
格式:
模块前缀+函数名称,如:
Sys_GetParameter()。
参数命名格式:
类型首字母(小写)+名称(首字母大写),如:
Sys_GetParameter(intiIndex)。
5>、类定义命名:
格式:
C+类名,类名尽量能做到清楚表达该类作用。
a.用于控制的封装类,格式:
C+类名+Ctrl;如:
CShowBtnCtrl。
b.对话框类,格式:
C+类名+Dlg;如:
CVideoShowDlg。
6>、文件命名:
遵循4.1命名原则,尽量做到词意表达清晰;对于类定义对应的头文件和实现文件,命名方法是将类名中的首字母“C”去掉,其余部分则作为该类的文件名称。
例如:
类CShowBtnCtrl,那么其对应的文件命名为ShowBtnCtrl.h和ShowBtnCtrl.cpp。
7>、界面设计中的控件命名(以VC为例):
a.对话框:
IDD_对话框名称+DLG如:
IDD_SIGLAMPDEFDLG。
b.对话框中的控件:
IDC_控件类型简写字母+名称。
如:
BUTTON:
IDC_BTNXXX;
COMBOBOX:
IDC_CMBXXX;
EDIT:
IDC_EDXXX;
LIST:
IDC_LISTXXX;
CHECKBOX:
IDC_CKXXX
注:
命名示例中“XXX”表示对应的名称。
5.代码风格
5.1代码书写原则
1>、注释和代码分别尽量对齐,力求整洁、美观。
2>、语句不宜过长,当语句过长时,按逻辑功能的不同或字符分段原则将其分行书写,分行同时应兼顾字符对齐,保持格式的统一。
3>、单行代码尽量简洁,保证代码易阅读,方便加注释,如只写一条语句,只定义一个变量。
4>、if、for、while、do、switchcase等语句单独占用一行,“{”和执行语句都不得紧跟其后,为保证美观和防止书写失误,无论执行语句多少行,即使是只有一行,都必须用“{}”将语句包含。
5.2对齐和缩进
1>、关键字(如if、for、while等)和“{”、“}”都单独占用一行,与其并列语句左对齐,并且位于同一列。
2>、“{}”之内的子代码块在“{”右边水平缩进4个空格对齐。
3>、代码文件的编写原则是从最左边界开始书写对齐,最顶层“{}”中的所有代码段都按上述两点原则逐级缩进。
5.3空格的使用
1>、在函数定义中分隔参数时,分隔符“,”后应加留空格,如:
voidfunction(intiParam1,intiParam2,intiParam3)。
2>、当“;”不是一行的结束符时,其后应加留空格,如:
for(i=0;i<100;i++)。
3>、一元操作符前不必加空格,如:
“!
”、“~”、“++”、“--”、“&”等。
4>、赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符等二元操作符的前后应加空格,与变量值分开。
如:
“=”、“+=”“>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等。
5.4括号的使用
1>、“()”与关键字之间,应用空格隔开,如:
if(li_count>0)。
2>、在表达式中,按子表达式逻辑功能的不同加“()”区分,尤其是在if语句表达式中,出现连续多个不同运算优先级的逻辑操作时,不加“()”不影响运算逻辑顺序的情况下,为代码的可读性,必须加上“()”按逻辑区分。
如:
if(nCount>0&&iState&ODS_CHECKED&&!
bCheckFlag),此语句虽是正确,但不推荐此种写法,为减少编码时的疏忽和对操作符运算理解的错误,推荐加上括号以区分,在一些特定时候和场合,有时画蛇添足也未偿不可,应改为:
if((nCount>0)&&(iState&ODS_CHECKED)&&(!
bCheckFlag))。
5.5空行的使用
1>、编码文件中的各个主体部分用空行分开;如文件注释和#include之间;消息映射和类定义之间等。
2>、各函数之间用空行分开。
3>、变量声明和代码之间用空行分开。
4>、代码按逻辑功能段加空行进行分开。
5>、代码行数较多时,视语句情况加空行以分开,以便于阅读。
5.6头文件引用
1>、在引用头文件时,要注意尖括号<>和双引号“”的用法。
#include
例如:
当开发过程中需要引用到第三方开发包的库文件,而这些库文件存放在其开发包安装目录中时,推荐将需要调用的库文件拷贝到当前工作目录中,并加入到工程中进行引用。
2>、自定义头文件时,需要注意加入条件编译语句,防止头文件被多次引用编译。
例如:
#ifndefFILENAME_H
#defineFILENAME_H
……
#endif
5.7代码发布原则
1>、代码正式提交或发布前,必须作好代码书写规范自查。
2>、检查模块外部接口注释描述是否完备,对外发布的调用接口是否方便简洁。
3>、为保证代码的工整性,发布前请删除在开发过程中增加的调试及测试代码。
6.代码示例对比
6.1代码行书写
1>、变量声明:
良好风格:
intiImgWidth;//图像宽度
intiImgHeight;//图像高度
intiImgBrightness;//图像亮度
不良风格:
intiImgWidth,iImgHeight,iImgBrightness;//图像宽度、高度、亮度;
2>、表达式:
良好风格:
x=a+b;
y=c+d;
z=e+f;
不良风格:
x=a+b;y=c+d;z=e+f;
良好风格:
if(a>b)
{
…….
}
不良风格:
if(a>b)return;或if(a>b){
…….
}
良好风格:
if((a>=b)&&(c<=d))
不良风格:
if(a>=b&&c<=d)
3>、函数定义:
良好风格:
voidFunction1(intiParame1,intiParame2,intiParame3);
不良风格:
voidFunction1(intiParame1,intiParame2,intiParame3);
6.2代码对齐
1>、“{”紧跟关键字或表达式后:
良好风格:
if(a>0)
{
//程序段
}
不良风格:
if(a>0){
//程序段
}
2>、代码段的对齐:
良好风格:
Voidfunction()
{
If(条件)
{
//代码段
}
Else
{
//代码段
}
Return;
}
不良风格:
Voidfunction()
{
If(条件)
{
//代码段
}
Return;
}
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 开发 编程 规范