软件编码规范(一) 作者:luhongjun
前言:
通过建立代码编写规范,形成BCB
开发小组编码约定,提高程序的可靠性、可读性、可修改性、可维护性、一致性,保证程序代码的质量,继承软件开发成果,充分利用资源。提高程序的可继承性,
使开发人员之间的工作成果可以共享。
软件编码要遵循以下原则:
1.遵循开发流程,在设计的指导下进行代码编写。
2.
代码的编写以实现设计的功能和性能为目标,要求正确完成设计要求的功能,达到设计的性能。
3.程序具有良好的程序结构,提高程序的封装性好,
减低程序的耦合程度。
4.程序可读性强,易于理解;方便调试和测试,可测试性好。
5.易于使用和维护;良好的修改性、扩充性;可
重用性强/移植性好。
6.占用资源少,以低代价完成任务。
7.在不降低程序的可读性的情况下,尽量提高代码的执行效率。
本规范的描述主要以 Borland C++ Builder 语言为例
一、 规范:以下对本规范作详细说明。
1:源程序的文
件管理:
a)组织:每个程序文件单元通常都应由 .cpp、.dfm和 .h 等文件组成,并将单元的公共声明部分放在 .h
文件中。划分单元主要是以类为依据,原则上每个较大的类都应为一个单独的单元,但在类较小且多个小类关系密切等情况下也可几个类共一个单元(建议仅对已经
详细测试的较为通用的类采用)。
b)命名:原程序文件命名采用有意义的格式。例如:对登陆程序来说三个文件的命名应该是这样,.cpp的是
Login.cpp .dfm的是Login.dfm .h的是Login.h
c)文件结构:每个程序文件由标题、内容和附加说明三部分
组成。
(A)标题:文件最前面的注释说明,其内容主要包括:程序名,作者,版本信息,简要说明等,必要时应有更详尽的说明(将以此部分以空行隔开单独注释)。
(B)内容:为文件源代码部分基本上按预处理语句、类型定义、变量定义、函数原型、函数实现(仅对 .cpp 文件)的顺序。 main 、
winmain ,控件注册等函数应放在内容部分的最后,类的定义按 private 、 protected 、 pubilic 、
__pubished 的顺序,并尽量保持每一部分只有一个,各部分中按数据、函数、属性、事件的顺序。
(C)附加说明:文件末尾的补充说明,如参考资料等,若内容不多也可放在标题部分的最后。
举例说明:
/*************************************************************
类:class TimageManipulation
设计者:lunhongjun (2001/05/09)
用途:用于图象
处理,实现图象亮度、对比度、反白、色彩平衡等处理
版本:
1.0 2001/05/09
完成基本的图象处理功能设计
2001/05/10 修改完成一个小Bug.
*************************************************************/
class TImageManipulation
{
private://define variant
Graphics::TBitmap * pSourceBitmap;//用于存放未经处理的原始图像
Graphics::TBitmap * pManipulatedImage;//用处存放经过处理后的图象
//图像处理过程中的相关参数
int iBrightness; //色彩亮度
int
iContrast; //色彩对比度
int iRedColorBalance;
//红色色彩平衡度
int iBlueColorBalance; //蓝色色彩平衡度
int
iGreenColorBalance; //绿色色彩平衡度
bool bRotate;
//字体旋转度数
bool bMonochrome; //是否反白显示
private:
void __fastcall BrightnessImage(void);//调整图象亮度
void
__fastcall ContrastImage(void);//调整图象对比度
void __fastcall
DoManipulationImage(void);//图象处理
void __fastcall
MonochromeImage(void);//图象反白
void __fastcall DoColor(void);
void __fastcall DoFilter(int * flt, int Div);
void
__fastcall RotateImage(void);//调整图象色彩平衡
public://define property
,method,event,function
__fastcall TImageManipulation();
__fastcall ~TImageManipulation();
void __fastcall
DoBrightness(int BrightnessIncrement);
void __fastcall
DoContrast(int ContrastIncrement);
void __fastcall
DoMonochrome(void);
void __fastcall DoChangeColorBalance(int
RedBalance,
int BlueBalance, int GreenBalance);
void
__fastcall SetSourceImage(Classes::TPersistent* Source);
Graphics::TBitmap * __fastcall GetManipulationImage(void);
void
__fastcall DoBlur(void);
void __fastcall DoSharp(void);
void __fastcall DoEmboss(void);
void __fastcall
LoadImageFromFile(AnsiString FileName);
void __fastcall
SaveManipulatedImageAsFile(AnsiString FileName);
TImageManipulation& operator=(const TImageManipulation &
imSource);
void __fastcall DoRotate(void);
};
#endif
2.编辑风格:
(1)缩进
缩进以4个空格为单位。建议在Tools/Editor
Options中设置General页面的Block ident为4,Tab Stop为4,不要选中Use tab
character。预处理语句、全局数据、函数原型、标题、附加说明、函数说明、标号等均顶格书写。语句块的“{”“}”配对对齐,并与其前一行对齐,
语句块类的语句缩进建议每个“{”“}”单独占一行。
(2)空格
变量、类、常量数据和函数在其类型,修饰(如
__fastcall 等)名称之间适当空格并据情况对齐。关键字原则上空一格,如: if ( ... )
等,运算符的空格规定如下:“::”、“->”、“[”、“]”、“++”、“--”、“~”、“!”、“+”、“-”(指正负
号),“&”(取址或引用)、“*”(指使用指针时)等几个运算符两边不加空格(其中单目运算符系指与操作数相连的一边),其它运算符(包括大多
数二目运算符和三目运算符“?:”两边均加一空格,“(”、“)”运算符在其内侧空一格,在作函数定义时还可据情况多空或不空格来对齐,但在函数实现时可
以不用。“,”运算符只在其后空一格,需对齐时也可不空或多空格,“sizeof”运算符建议也在其后空一格,不论是否有括号,对语句行后加的注释应用适
当空格与语句隔开并尽可能对齐。
(3)对齐
原则上关系密切的行应对齐,对齐包括类型、修饰、名称、参数等各部分对齐。另每一行的
长度不应超过屏幕太多,必要时适当换行,换行时尽可能在“,”处或运算符处,换行后最好以运算符打头,并且以下各行均以该语句首行缩进,但该语句仍以首行
的缩进为准,即如其下一行为“{”应与首行对齐。
变量定义最好通过添加空格形成对齐,同一类型的变量最好放在一起。如下例所示:
int Value;
int Result;
int Length;
DWORD Size;
DWORD BufSize;
char * pBuf;
void * pOutputBuf;
LPCSTR * pPath;
(4)空行
程序文件结构各
部分之间空两行,若不必要也可只空一行,各函数实现之间一般空两行,由于BCB会自动产生一行“//------”做分隔,另因每个函数还要有函数说明注
释,故通常只需空一行或不空,但对于没有函数说明的情况至少应再空一行。对自己写的函数,建议也加上“//------”做分隔。函数内部数据与代码之间
应空至少一行,代码中适当处应以空行空开,建议在代码中出现变量声明时,在其前空一行。类中四个“p”之间至少空一行,在其中的数据与函数之间也应空行。
(5)注释
对注释有以下三点要求:
A.必须是有意义。
B.必须正确的描述了程序。
C.必须是最新的。
注释必不可少,但也不应过多,以下是四种必要的注释:
A.标题、附加说明。
B.函数说明。对几乎每个函数都应有适当的说明,通
常加在函数实现之前,在没有函数实现部分的情况下则加在函数原型前,其内容主要是函数的功能、目的、算法等说明,参数说明、返回值说明等,必要时还要有一
些如特别的软硬件要求等说明。
C.在代码不明晰或不可移植处必须有一定的说明。
D.及少量的其它注释。
注释有块注释
和行注释两种,分别是指:“/**/”和“//”建议对A用块注释,D用行注释,B、C则视情况而定,但应统一,至少在一个单元中B类注释形式应统一。
举例如下:
/***************************************************************************
函数名称:ResultType MyFunction(ParamType1 Param1, ParamTyp2,Param2)
功
能:该函数主要是完成如下的功能
设计目的:设计该函数主要是为了解决。。。
设计原理:该函数是这样设计的。。。
实现
方法/过程:为了实现函数的目的,这个函数是这样实现的。。。
出入口参数:
ParamType1
Param1:类型ParamType1,这个参数是。。。
。。。
返回值描述:
设计修改日志:
2001/4/16 第一次设计
2001/4/17 修改了。。。
2001/4/18 添加了。。。删除了。。。
相
关函数:
其他补充说明:
**************************************************************************/
ResultType MyFunction(ParamType1 Param1, ParamTyp2,Param2)
{
int Value;
int Result;
DWORD Size;
char * pBuf;
。。。。
}
(6)代码长度:
对于每一个函数建议尽可能控制其代码长度为53行左右,超过53行的代码要重新考虑将其
拆分为两个或两个以上的函数。函数拆分规则应该一不破坏原有算法为基础,同时拆分出来的部分应该是可以重复利用的。对于在多个模块或者窗体中都要用到的重
复性代码,完全可以将起独立成为一个具备公用性质的函数,放置于一个公用模块中(Common.cpp/Common.h)
3.符号名的命名
(包括变量、函数、标号、模块名等)
选用有实际意义的英文标识符号或缩写符号,名称中尽可能不使用阿拉伯数字,如这样的名称是不提倡
的:Value1,Value2,Value3,Value4…..。
例如:
file(文件),code(编号),data(数
据),pagepoint(页面指针), faxcode(传真号) ,address(地址),bank(开户银行),……
变量名称:由
(前缀+修饰语)构成。
(1)生存期修饰:用l(local)表示局域变量,p(public)表示全局变量,s(send)表示参数变量
(2)类型修饰:用s(AnsiString)表示字符串,c(Char)表示字符,n(number)数值,i(intger)表示整
数,d(double)表示双精度,f(float)浮点型,b(bool)布尔型,d(date)表示日期型.
例如:
li_length表示整形的局域变量,是用来标识长度的.ls_code表示字符型的局域变量,用来标识代码.
控件名称:由(前缀+修饰
语)构成。前缀即为控件的名称。
按钮变量 Button+Xxxxxxx
例如:ButtonSave,ButtonExit,ButtonPrint等
题标变量 Label+Xxxxxxxx
例如:LabelName,LabelSex等
数据表变量 Table+Xxxxxx
例如:TableFile,TableCount等
查询变量 Query+Xxxxxx
例如:QueryFile,QueryCeneter等
数据源变量 DataSource+Xxx
例如:DataSourceFile,DataSourceCenter等
。。。。。。。。。。。。。。。。
(注:对于与表有关
的控件“修饰语”部分最好直接用表名。)
4:输入输出
输入和输出方式和格式尽可能方便用户,避免因设计不当给使用带来麻烦。应根
据不同用户的类型、特点和不同的要求来制定方案。格式力求简单,并应有完备的出错检查和出错恢复措施。
界面布局主要考虑各区域在屏幕的放置,
使用户能以最快的速度找到操作对象、发现目标,屏幕的布局还要考虑界面的表现形式,使界面美观一致,协调合理。界面设计要求满足以下要求:
●
界面上只包含必要的信息。
●界面上包含所有必要的信息。
●界面布局从左上角开始。
●制订格式标准,所有的屏幕设计都
遵守这些标准,保持一致性。
●根据逻辑关系将相关的信息放在一起。
●屏幕设计要保持对称的平衡。
●避免过多使用前调
信息。//例如OnEnter事件请尽量少用。
●区分标题和内容。
●提示信息要简洁。
●设计与用户知识和经验一致。
●按照使用顺序显示信息。
●遵照流行软件的事实标准。
●选择合理的显示方式。
●尽可能不让用户切换画面即可完成一
次完整的操作。
5:其它程序技巧
程序中增加合理适量的注释。程序的注释作为评测考核的一个重要指标。
在程序设计时,
应该全面考虑出现可能存在的例外情况的处理。应该有一个良好的错误处理和例外处理机制,在处错误的时候能保证程序能正常运行/退出,不会造成用户的数据丢
失/损失。对于发生意外错误或例外是要能记录当时的运行情况并且用户可将这个信息返回给开发人员。
避免使用相似的变量名,变量中尽量不含数
字。
同一变量名不要有多种意义。
显示说明所有变量。
注意浮点运算的误差,少用浮点数比较。
注意整数运算
的特点。
少用或不用GOTO语句,即使用GOTO不要相互交叉。
尽量少用全局和静态变量。
提高程序的封装性,降低程
序各模块的耦合性。
提高程序的可继承性,建立通用的函数库、控件库,使开发人员之间的工作成果可以共享。
软件编码规范(二)
作者:seahorse
源程序命名规定
1)总则:
文件名全部用小写字母。
源文件后缀为.c或.cpp
头文件后缀为.h。
2)为了清楚地区分各个子模块、子系统,建议使用以下标识作为源文件的前
缀:
子模块:
sms_ 公共文件
com_ 通讯部分
uim_ 用户届面
dba_ 数据库访问
test_ 测试程序
通讯模块中的子部分:
prc_
进程内调度机制
dlg_ 会话与事务机制
cfg_ 可配置机制和配置中心子系统
wrk_ 监视告警日志机制
db_ 数据库代理子系统
log_ 日志子系统
mon_ 监视子系统
warn_ 告警子系统
3)文件头部声明格式
文件名 : 文件名 (eg:ADD.c)
作者 : 作者姓名 (eg:牛顿)
日期 : 该文件创建日期 (eg:2000/8/1)
文件功能 :
该文件所能实现的功能 (eg:One of the source files for the class CEdit)
版本 : 版本号 (eg:1.0)
编译环境 : (eg:VC++6.0,GNU)
实现环境 : (eg:Windows98,Helio 3.2)
注释 :
对文件的附加说明(包括那些函数和全局变量)
修改者姓名 (eg:爱因斯坦) 修改时间 (eg:2000/9/1)
对所修改内容的详述
...
版权声明 :
---------------------------------------------
(eg:
Copyright (c) 2000 MicroSoft .All rights reserved. )
五.类和变量的规定
1) 尽可能为每个类创建两个文件(.c和.h文件)。可以采用前缀加上类名的方法构成一文件名。不要怕文件名太长。
为每个类单建文件,是为了维护的方便,便于查找、修改,跟据类名可以直接找到文件名。
可以将数目不多、代码量不大的密切相关的几个类放在一对.h/.c文件中。公用类是可以放在一起的。
2) 类(自己定义的)的名字以大写的 C
开头。
结构的名字以 St 开头。
枚举类型的名字以 En 开头。
联合的名字以
Un 开头。
自定义的简单数据类型以 T 开头。
这些前缀后面跟以大写字母开头的单词。
3) 对变量的声明:
变量的名字以能够反映该变量类型或性质的一个或多个小写字母开头(根据匈牙利规则 ;
匈牙利规则----变量类型由一个或两个字符表示. )
一些常用的表示如下:
-----------------------------------------
前缀 |
数据类型
-----------------------------------------
c | char
d | double
s | string
i |
integer
l | long
x,y
| integer,long(分别用作x,y座标时)
cx,cy |
integer,long(分别用作x,y长度时)
b | BOOL
p | 指针
---------------------------------------------
4)
函数(类成员函数可以出外)和宏定义,注释:
函数的名字以大写单词开头,采用大小单词混写的方式,可以使用常用的缩写不使用小写字母加下划线的方式。 函数的命名要表明它的作用,不要怕名字长.
例:GetMaxLength();
除非是在函数体内部,不得使用原始的简单数据类型,应该为各种类型的数据定义有意义的能够反映该数据的特征的数据类型。
函数的参数类型应该尽可能使用自定义的类型。
函数的返回值尽可能使用枚举类型,或者使用自定义的类型。
函数头部声明格
式:
函数名 : 函数名
日期 : 该函数创建日期
函数功能 : 该函数所能实现的功能
参数说明 :
对函数的输入输出参数、返回值、用到的全局变量加以说明
...
宏定义的名字全部用大写字母。不要试图用宏定义代替函数。宏定义不要太长。注意宏定义时括号的完整性。对于宏定义的常数、表达式等一定要用括号括起来。
对于标志性的值,或者已知几种情况的值,应该使用枚举类型定义有意义的名字或是宏定义,而不是用整型。
编译符号的名字以下划线开头,后面用大写字母和下划线混写。
边写代码边写注释。短小的注解应当具有启发性,对阅读程序有用。如果在写代码时便写注释,而不是所有工作都完了再返回头来加注释,可以避免许多错误。对于
在开始时不愿花时间去写长篇的程序头说明和函数描述是可以理解的,但在写代码时加入短小的注解总是有时间的。
5)控件的命名:
原则:控件的Name属性命名既要表明控件类型又要表明用途,常用的约束如下
Name =
控件名(小写前缀)+用途(单词的首字母大写)
***************************************************************
对象 前缀 例子
***************************************************************
Form(窗体) frm frmFileOpen
Label(标签)
lbl lblHelpMessage
Frame(框架)
frm frmLanguage
CheckBox(复选框) chk
chkReadOnly
ComboBox(组合框) cbx cbxEnglish
ListBox(列表框) lst lstPolicyCodes
Timer(定时器) tim timAlarm
Shape(形状(圆,正方形..)) shp shpCircle
Image(图像)
img imgIcon
(注:开发人员发现未出现在规范中的控件,应及时向编码规范编写者上报,以确
定其规范)
6) 菜单的命名:
主菜单:使用前缀mnu+当前菜单标题 例:File -->
mnuFile
子菜单:使用前缀mnu+当前主菜单标题+当前菜单标题
例:File下的Open--->mnuFileOpen
六、编程规则
1)首先要满足软件编程规范总则和数据库分则的要
求。
编程人员不得随意更改设计,如有需要,必须通报设计人员,设计人员认可后,才能更改。设计方案中涉及到的类,不得随意定义Public类型的函数,或者更
改类函数或成员变量的属性(Public,Protect,Private,Virtual)。
2)全局变量的定义一定要得到设计人员的许
可。不得使用简单的全局变量,可以定义少数的全局对象。可以将全局变量放在一个专门的类中,通过函数接口访问变量。
变量(全局,局部)也要初始化。
3)析构函数通常情况下应被声明为虚的,否则,会有不正确地析构了对象的风险。
例如:BaseClass *pB=new ChildClass; ... ; 当delete
pB时,如果BaseClass的析构函数不是虚函数,则不会调用ChildClass的析构函数。如果不将析构函数声明为virtual,则要给出注
释,指明理由。只要将最早的基类的析构函数指明为virtual即可。
不能用拷贝构造函数代替赋值运算符的重载。如果有一个非缺省构造函数,则必需重定义缺省构造函数。虚函数不能是类的内联(inline)函数。构造函数不
能是虚的。赋值运算符的重载必需作为类的成员函数。
4)指针一定要初始化,不得使用未经初始化或没有赋值的指针。使用指针之前要判断其是否为空,释放指针后将指针设置为空。建议不去释放空指针(虽然在有的
系统上,释放空指针没有坏的后果)。 指针使用完毕要及时释放。一般来说,在析构函数内,应该做释放内存的工作(释放对象运行中动态分配的内存)。
对于链表,最后一个对象的next指针一定要设置为空。
5)注意数组的越界问题,一定要判断数组的元素个数.对于已知长度的字符
串,应该预先定义好数据类型,然后使用该自定义类型,而不要使用char*。为字符串分配空间要注意多一个字节
6)除非是在函数体内部,不得
使用原始的简单数据类型。应该为各种类型的数据定义有意义的能够反映该数据的特征的数据类型。
7)函数的返回值尽可能使用枚举类型,或者使用
自定义的类型。对于标志性的值,或者已知几种情况的值,应该使用枚举类型定义有意义的名字,而不是用整型。函数的参数类型应该尽可能使用自定义的类型。
8)对数据类型(包括简单数据类型、公共的结构,不包括类)的定义,放在统一的公共文件中(暂定sms_datatype),不得在其它地方定义数据类
型。在公共文件sms_datatype中统一定义数据类型的好处是便于修改,同时可以对系统的数据有一个总体认识。
9)不依赖于特定的子系统、可以为多个子系统所用的公共函数的定义,放在公共文件sms_pub.h和sms_pub.c中。
10)对基础
类、公用类的定义放在公共文件sms_class.h和sms_class.c中。对于已经在sms_class.h
(.c)中实现的类,不得再定义与之相近的类。对于同样的或相近的功能,不得定义多个类。
11)字符串指针作为函数参数时,要注意输入、输出
参数的区别。同时注意指针本身是否可以被修改。如果可以修改指针,还要注意是否要重新分配空间。
12)小心使用strcpy,尽可能不用它,可以使用strncpy或memcpy代替(别忘了在目标字符串后加上'\0',可以自定义一个
StrCopy函数,拷贝一定数量的字符后自动在目标字符串后加上'\0')。例:(在文件sms_pub.c中已经定义)
Int StrCopy(PSTR dest, PSTR src, UInt maxLength)
{
if (!dest || !src)
return -1;
strncpy(dest, src, maxLength-1);
dest[maxLength-1]=0;
return 0;
}
13)采用==进行比较时,注意尽量将常数或值放在前面,将变量放在后面,用以避免将==错写成=的错误。尽量在错误信息、提示信息等中不使用字符串常
数。可以将字符串常数统一在一个头文件用宏定义(对于所有的错误类型的定义放在sms_error.h中),以便于改变语言环境。
14)不要
在.h文件中定义类的成员函数(指的是对函数的实现),而应该在.c或.cpp文件中定义。只在.h文件中定义类的结构,对类的成员函数做声明。尽可能使
用标准的C++。不要对编译器做任何假设,尽量编写与平台无关的代码。因为,我们开发的系统需要支持多平台,可移植性很重要。如果必须用到与平台相关的代
码,要加上显著的注释,以及使用编译符号来判断具体的平台。
阅读(789) | 评论(0) | 转发(0) |