编程规范文档格式.docx
- 文档编号:7929479
- 上传时间:2023-05-09
- 格式:DOCX
- 页数:30
- 大小:30.77KB
编程规范文档格式.docx
《编程规范文档格式.docx》由会员分享,可在线阅读,更多相关《编程规范文档格式.docx(30页珍藏版)》请在冰点文库上搜索。
3.1基本规则
标识名分为两部分:
规范标识前缀+含义标识,标识的总长度不要超过32个字符。
这里的标识是指语言中语法对象的名字,它们有常量名、变量名、函数名、类和类型名及预处理名,标识名的基本语法是以字母开始,由字母数字及下划线组成的单词,我们将标识划分成这两个部分是基本如下原因:
(1)用规范标识前缀来标名该标识所属的应用系统,以便在应用系统间互相区别
(2)用规范标识前缀来标名该标识的归类特征,以便与其它类型的标识互相区别
(3)用含义标识来标名该标识所对应的被抽象的实体,以便记忆
(4)用这种命名法来区分本公司标识与外公司标识
3.2含义标识命名及书写规则
(1)命名:
按其应用的含义由一个或多个词组成.词可以是中文词或英文词.
(2)书写:
每个词的第一个字母大写,其余全部小写,词与词紧连(宏和枚举除外),宏和枚举值标识全部大写,词与词可用下划线分开.
中文词由中文描述含义的每个汉字的头一个拼音字母组成;
英文词尽量不缩写,除非这种缩写比较通用,不要在同一系统中对同一单词使用不同的表示法(如全写和缩写均使用).全由大写字母组成的缩写词,书写仅第一个字母大写,其余全部小写.
3.3规范标识前缀
规范标识前缀的命名由标识所属类型的前缀命名规范决定,它总是由1个或多个不超过3个字母的缩写词组成.
规范标识前缀分为四类:
(1)变量前缀
(2)类型、类前缀
(3)宏和枚举常量前缀
(4)函数及共用API前缀
其中
(2),(3),(4)说明了那些可供外部程序使用的对象标识的表示规范,而
(1)说明了内部变量的表示规范.
本规范中没有关于全局变量的表示规范,这是因为全局变量与局部变量混淆所产生的错误是极为难以排除的,所以在本规范中严禁使用全局变量.对全局资源的存取要求封装在函数内,例:
禁止使用的方法:
externinterrno;
建议的使用方法:
constintGetErrorNo(void);
voidSetErrorNo(constint);
类变量前缀为了能够方便的区分类变量和局部变量,建议采用VisualC++的规范,在全局变量前加“m_”。
3.3.1变量前缀
变量前缀采自目前最流行的Microsoft的匈牙利标记法,由于这套方法专用于PC机上的C编程,在此,我们做必要的改动以适应C++及多平台编程的需要.
变量前缀是利用一个或多个小写字母来表示变量的类型信息,帮助设计者避免C/C++类型匹配和自动转换错误,例如将长整按布尔值使用时,只要其低16位为0,在PC机上的编译程序一般认为是假.
作为变量总是以小写字母打头,这使得与常量类(如函数,类名等,它们总是以大写打头)明显区分开来,事实上几乎所有的编译程序在这两类名同名时,报错信息极不准确,这种区分可以避免这种错误的产生.
前缀
代表的数据类型
举例
以下可作前缀的前缀
a
arrayof
char[10]achVariable;
u
unsigned
unsignedintuiVariable;
l
long
longlVariable;
d
double
doubledVariable;
p
pointer
long*plVariable;
r
referece
int&
riVariable;
c
const
constintciVariable;
h
objecthandle
HPENhWindow;
f
flagvariable
unsignedintfuiVariable
以下不能作前缀的前缀
ch
char
charchVariable;
s
short
unsignedshortusVariable;
i
int
inti;
e
enumvariable
enumAeVariable;
w
word(unsignedshort)
unsignedshortwVariable;
dw
doubleword(unsignedlong)
unsignedlongdwVariable;
b
boolean(int)
intbVariable;
by
unsignedchar
unsignedcharbyVariable;
hz
chinesechars
w_char*hzVariable;
fn
function
(*fnVariable)(void);
sz
null-terminatedstring
char*szVariable;
v
void
void*pvVariable;
rec
structvariable(advised)
structArecVariable;
注:
如上表示中ch前缀是有二义性的,它即表示一个char类型又表示一个consthandle类型,但这里的c,h,ch三个缩写已广为使用,我们在此建议将consthandle表示为hc.
sizeof当操作p打头的变量返回指针的长度,而以a打头的变量则会返回数组所占空间的长度,虽然C/C++对指针和数组比较混乱,但这种前缀表示法还是可以使你免除一些麻烦。
自定义类型和类的变量,一般将类名的含义标识第一个字母变为小写作为变量名即可,如果经常使用该类可自定义对应于该类的变量缩写前缀.
OBcObjectobject,objectName,objectAge;
其中OBcObject为一个类名.
3.3.2类型和类前缀
以该代码所在的应用系统的缩写为准,长度不超过3个,全部大写.C语言不支持类,C++现行标准将类与类型已等同对待,所以命名中我们不必区分这两种。
除变量以小写字母打头以外,几乎其它标识在本规范都以大写字母打头,为更加清楚的说明本类标识的特征,本规范建议类型和类的前缀,在其应用系统缩写名后紧跟小写字母的类型区别符。
typedefunsignedOBuiMachineWord;
typedefenumtagOBeOpenMode
{//fileopenmode
OBE_MODESHAREREAD,
OBE_MODEEXCLUSIVE,
OBE_MODESHAREUPDATE
}OBeOpenMode;
typedefstructtagOBcHandle
{//definedthetypejustforstrongtypecheck
unsignedinth;
}*OBcHandle;
classOBcIncreaseMemory
{//amemorycanbeincreasedautomaticaccordingtodataappend
public:
OBcIncreaseMemory();
//initalldatamemberwithzero
~OBcIncreaseMemory();
//deleteoccupiedmemory
Add(int);
//addaintegerinto
Add(char*sz);
//addanullterminatedstringinto
private:
unsignedintuiCursor;
void*pvMemory;
};
c类型标识表示结构或类、其它类型标识与变量前缀相同、OB是OpenBASE系统的缩写。
虽然在Windows系统中类型名使用的是变量规范(但全部是大写),但在今天的以类为中心的主要编程方法形式下,类型和类通常是很多的,这种命名法的易读性实在是很糟糕的,因此本规范不采用这种命名法.
3.3.3宏和枚举的前缀
宏是一个极不安全的机制,它能产生一些非法或非本义的语句,而你确很难找出错误的原因,它在绝大多数使用情况下会使代码冗长而低效.在C/C++中增加了枚举、inline、常变量和template机制来避免使用宏,这些机制可以基本替代宏的使用.但宏是一个语言之上的语言,它能拼凑语句,而这种能力在C/C++这种本语言级是无法实现的.
宏和枚举的前缀建议使用应用系统缩写加变量前缀命名方法,但得全部大写并后加一个下划线.
例:
#defineOBSZ_ROOTPAHT"
C:
\OPENBASE"
//theopenbasesystemrootpath
//agoodstyleisusingC++constvariable,definedas:
//constchar*constcszcRootPath[]="
;
#defineOBFN_ABS(x)((x)>
0?
(x):
-(x))//theabs(x)forallnumerictypedata
//youalsocanuseC++templatetoimplementthefunction
#ifdef_Windows_
#defineOB_DLLPASFUNC_export_pascal
#elifUNIX
#defineOB_DLLPASFUNC
#else
#errorOB_DLLPASFUNCundefinedinthecompiler
#endif
typedeftagOBeOpenMode
{
3.3.4函数的前缀
函数的前缀与类和类型表示法类似,它以应用系统的缩写为前缀,后面紧跟一个小写字母f和关于函数返回值的类型描述符,函数的返回值通常被划分为值返回,错误返回和指针返回这三类:
(1)值返回类的函数总是能正确执行并返回结果值或void(无结果)
(2)错误返回类函数返回值类型总是整数,该整数值用来表示错误的类型,通常有三种表示方法:
1、返回-1为失败(UNIX风格),如果返回值同时被表示为某个对象的标识(或称为把柄),则其它值为该对象的标识,否则只有0表示执行成功,其它为无定义值.表明错误原因的错误码需调用一个专门的GetErrorNo()之类的函数返回.2、返回假为失败,其它为成功(Windows风格),表明错误原因的错误码需调用一个专门的GetErrorNo()之类的函数返回.3、返回结果码,系统设立一个返回结果码表(内含执行成功的码号及各类错误的码号),用户通过用结果值与结果码表进行比较来确定函数是否执行成功.如上三种方法在使用时是互斥的,即您在一个应用系统中只能选择一种方法.
(3)指针返回类函数返回空指针说明该函数执行失败,其它值则为一个合法的指针值,该值通常指向用户所需要的数据或数据空间.表明错误原因的错误码需调用一个专门的GetErrorNo()之类的函数返回.
在此我们规定函数返回值类型描述符为:
(1).n为错误返回类,如无其它后缀则表示返回-1为失败
(2).ni表示返回错误号
(3).nb表示返回假为错误
(4).变量前缀:
结果返回类,其中如果返回值为指针类或把柄类,返回空为错误.
(5).为了不使函数名中的类型描述符过长,指向对象的指针和把柄应缩写为p和h.
(在本例中未给出返值类型说明的按C语法均为整数)
OBfnOpen(constchar*szObjectName);
//OpenaObjectaccordingtoname,returntheobjecthandle;
//return-1isaerror,youcancallOBfGetErrorNo(void)togeterrornumber.
OBfniOpen(constchar*szObjectName,int*piObjectHandle);
//OpenaObjectaccordingtoname;
//ifreturnOBE_SUCCESS,theobjecthandleisputinto*piObjectHandle;
//elseisaerrorandreturntheerrornumber.
OBfnbOpen(constchar*szObjectName,int*piObjectHandle);
//ifreturntrue,theobjecthandleisputinto*piObjectHandle;
//elseisaerror,youcancallOBfGetErrorNo(void)togeterrornumber.
OBfOpen(constchar*szObjectName);
//itisalwayssuccess.
voidOBfvOpen(constchar*szObjectName,int*piObjectHandle);
//theobjecthandleisputinto*piObjectHandle;
OBcObject*OBfpOpen(constchar*szObjectName);
//OpenaObjectaccordingtoname,returnapointertotheobject;
//ifreturnnull,itisaerror,youcancallOBfGetErrorNo(void)toget
//errornumber.
OBfhOpen(constchar*szObjectName);
//ifreturn0,itisaerror,youcancallOBfGetErrorNo(void)toget
之所以作这样的规定是为了我们能够通过函数名来确定函数返回的类型及对错误的处理方法,这方便了C/C++编程人员对函数的返回值(尤其是错误类)作仔细处理.
3.3.5局部对象的简化命名
本规范的局部对象是指其标识作用域在一个函数内、一个文件内或一个类内的对象,它们有局部变量、局部常量、局部函数(static类函数)、局部类和类型,这些对象仍可使用全局类命名法命名,对于局部函数和局部类及类型也可以去掉应用系统缩写和类型描术符.
3.3.6临时对象命名规则
程序中的临时变量有别于局部变量,它是指作用范围不超过一个程序块,用来存储临时返回值、临时缓冲、临时计数等等。
临时变量的命名可以采用全小写的原则,采用一些比较通用的名称,如i、n、count、buffer、tmp、prt等等。
注意:
临时变量的值在超出当前程序块后,不应该再有意义。
临时变量的声明一般只在需要的时候才声明。
例如:
for(inti=1;
i<
10;
i++)
{
......
}
for(i=100;
200;
4.1注释原则
程序应以其本身的算法设计,功能划分,逐级抽象和自说明性为提高易读性的主要手段.不需要注释的程序是最理想的,但C/C++远没有自然语言那么容易书写和理解,适当的注释是十分必要的.
(1)注释不是重复程序,它应该提供更多的信息,否则应该不写.
(2)注释是需要维护的,错误的注释害人害已.
(3)注释总是加在程序的需要一个概括性说明或不易理解或易理解错的地方.
(4)注释应语言简炼、易懂而又准确,所采用的语种首选是中文,如有输入困难、编译环境限制或特殊需求也可采用英文.
不好的表示:
for(i=1,i<
8;
...
易读的表示
typedefenumtagWeekDay
Mon,
Tue,
Wed,
Thu,
Fri,
Sat,
Sun
}WeekDay;
WeekDayday;
for(day=Mon;
day<
=Sun;
((int)day)++)
数字所能表示的东西实在的太多了,从理论上讲,数字可以表示人类所能认知的一切,第二段程序很清晰的表示了一个关于星期的循环而无需加任何注释,这是一个增加程序自说明性的例子,如果你使用英文国家的软件,你会发现一个令你惊呀的事情,他们将星期日表示为1,星期一是2?
!
如果你仔细观察日历,你会发现第1列总是星期日...
4.2常量和变量的注释
在量名字的C/C++或宏声明后应对该名字作适当注释,注释说明的要点是:
(1)被保存值的含义(必须)
(2)合法取值的范围(可选)
(3)与其它数据,函数或模块的关系(可选)
(4)全局量需要对以上逐点做充分的说明.
4.3类型的注释
对类型的注释应按照数据字典说明来写,说明要点是:
(1)它描述的对象是什么(必须)
(2)建立在该类型上的操作(函数)有哪些(必须)
(3)对其分量应按§
3.1要求加以注释(必须)
(4)与其它数据,函数或模块的关系(可选)
4.4函数的注释
(1)在函数的原型说明后应作适当注释,说明该函数的功能,及各参数的含义.
(2)在函数的定义(实现)部分,如算法复杂时,应以注释的方式对其算法结构作出说明.
(3)函数申请过全局资源且有可能导致资源紧张应加以注明(如内存,文件柄等).
(4)函数有副作用一定以十分醒目的方式(如加!
号等)注明
4.5类的注释
类是类型和函数的统一体,对类的注释与类型相同,对数据成员的注释与变量相同,对函数成员的注释与函数相同.
4.6语句的注释:
(1)应对不易理解的分枝条件表达式加注释.
(2)不易理解的循环,应说明对出口条件(有GOTO的程序还应说明入口条件).
(3)过长的函数实现,应将其语句按实现的功能分段加以概括性说明
5.1模块划分的准则:
(1)实现相关密切的一组类,类型,常量,变量,宏和函数(高内聚准则)
(2)提供给外部的功能可以通过不超过百行的C/C++说明描述出来(低耦合准则).
(3)过多的外部说明,应考虑与其他模块合并或重新划分.
(4)实现部分的总代码应在千行以内.超大的模块应考虑进一步细分.
5.2模块的文件构成:
一个模块是由C/C++源程序文件开发文档组成,本规范要求一个模块应被分为如下三个文件:
(1)提供给外部的类,类型,常量和宏定义,函数的原型说明,变量的外部声明.文件名应以模块名后缀.h(C++可以是.hpp)
(2)对外隐蔽的类,类型,常量和宏定义,函数的原型说明,变量的声明及函数实现.文件名应以模块名后缀.c(C++可以是.cpp|.cxx)
(3)模块开发卷宗,以模块名后缀.mdf
5.3模块的开发步骤建议
(1)编写模块开发卷宗
(2)设计编写提供给外部的类或函数原型及相关的参数类型定义
(3)给出这些原型的DEMO实现
(4)设计出提供给外部的类,类型,常量和宏定义,变量的外部声明.
(5)内部实现设计
(6)编码
(7)模块测试(包括编写模块的驱动和支撑程序)
(8)组装测试
5.4模块设计编写注意事项:
(1)与外部的数据交换应以函数的参数形式,而不要使用全局变量.
(2)内部函数间的数据交换也应以函数的参数形式为主,以使用类数据成员或文件内可见的静态数据变量为辅.
(3)在C++中模块的外部界面应该用一个类定义描述.
6.1函数划分的准则:
良好的函数划分,能够自项向下逐级抽象地展现设计思想,提高程序的易读性和自说明性.
(1)函数是按功能划分的,每个函数应该只做一件事情(高内聚准则).
(2)相关的一组函数关联应不多(低耦合准
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 编程 规范