软件编码规范.docx
《软件编码规范.docx》由会员分享，可在线阅读，更多相关《软件编码规范.docx（27页珍藏版）》请在冰点文库上搜索。
软件编码规范
天正软件编码规范
一、命名规范
1、通则
1.1、在所有命名中，都应使用标准的英文单词或缩写，避免使用汉语拼音。
1.2、所有命名都应遵循达意原则，即名称应含义清晰、明确。
1.3、所有命名都不易过长，在可表达清晰的前提下越简洁越好。
1.4、所有命名都应尽量使用全称。
1.5、在类型名称特别复杂的时候，应使用typedef来定义别名。
2、标识符
2.1、标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。
（较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写）
如下单词的常用缩写
applicationapp
argumentarg
averageavg
blockblk
bufferbuf
commandcmd
controlctrl
databasedb
deletedel
descriptiondesc
dialogdlg
dictionarydict
dimensiondim
distancedist
documentdoc
entityent
escapeesc
flagflg
increaseinc
informationinfo
lengthlen
librarylib
managermgr
memorymem
messagemsg
objectobj
passwordpwd
picturepic
ploylinepline
pointerptr
positionpos
recordrec
referenceref
resourcersc
screenscr
serversrv
sourcesrc
systemsys
temptmp
texttxt
versionver
windowwnd
VC++中常用控件缩写
Animateani
CheckBoxchk
ComboBoxcmb
Editedt
GroupBoxgrp
ListBoxlst
Picturepic
Progressprg
PushButtonbtn
RadioButtonrad
ScrollBarsb
Slidersld
Staticstc
TabControltab
2.2、长的标识符应使用缩写来缩短长度，而特短的标识符应该避免使用缩写。
更恰当：
intiFlag
HMODULEhLoadedSysRsc
不恰当：
intiFlg
HMODULEhLoadedSystemResource
2.3、变量和封装体命名中单词或缩写的第一个字母应大写，其它字母小写，单词和单词之间直接连接，不得有其它字符。
在宏定义中全部用大写，单词与单词之间必须用下划线连接。
正确：
TempResource
#defineREG_KEY
错误：
Temp_Resourcetemp_resource
tempresource
#defineReg_Key
2.4、除了编译开关/头文件等特殊应用，应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义。
2.5、对于变量命名，禁止取单个字符（如i、j、k...），命名除了要有具体含义外，还能表明其变量类型、数据类型等，但i、j、k等作局部循环变量是允许的。
2.6、命名时，如果需要进一步分类时，分类属性应放在前面。
正确：
CListBoxm_wndLstFonts;
CComboBoxm_wndCmbColors;
错误：
CListBoxm_wndFontsLst;
CComboBoxm_wndColorsCmb;
2.7、命名中若使用特殊约定或缩写，则要有注释说明。
（应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说明）
2.8、在命名规范中没有规定到的地方，才可以使用自己特有的命名风格，要自始至终保持一致，不可来回变化。
2.9、除非必要，不要用数字或较奇怪的字符来定义标识符。
正确：
#defineEXAMPLE_TEST
TestLockDriver
错误：
#defineEXAMPLE_0
Test123
2.10、在同一软件产品内，应规划好接口部分标识符的命名，防止编译、链接时产生冲突，可在普通标识基础上加上模块标识。
示例：
在TGRX模块中可定义为CTGRxObjectg_rxRegistry
在TGDB模块中可定义为CTGDbBlockRecordg_dbGlobal
在TGGui模块中可定义为CTGUiFrameWndg_uiCmdMgr
2.11、命名规范必须与所使用的系统风格保持一致，并在同一项目中统一，比如有关STL的代码应使用STL中的全小写加下划线的风格，有关MFC的代码则使用大小写混排的方式。
3、封装体
3.1、采用前缀和以大写开头的英文单词或缩写组成，即：
前缀+标识符。
简写类型说明
Cclass类
Sstruct结构体
Eenum枚举
Uunion联合体
示例：
classCTree{};
structSResBuf{};
enumESeekType{};
unionUResVal{}；
4、变量
4.1、变量命名应遵循匈牙利记法，即：
前缀+类型+标识符。
4.2、前缀
简写类型说明
m_classmember类的成员变量
s_staticvariable静态全局变量
g_globalvariable普通全局变量
注意：
1、struct/union中的成员变量不加前缀，即：
类型+标识符
2、const成员变量应使用k+标识符
3、enum中的成员应使用k+标识符
示例：
m_arsNamem_lFilePos
s_cConfigs_iLoopTimes
g_hResouceg_sModuleName
structSTreeData
{
HICONhTreeIcon;
TCHARszTreeName;
}；
classCVector3d
{
constCVector3dkIdentity;
constCVector3dkXAxis;
}
enumEDirection
{
kLeft,
kRight,
};
enumEErrorStatus
{
kOk,
kOutOfMemory,
};
4.3、类型
基本类型
简写类型说明
bybyte字节
bbool布尔型
nshort短整型
nUINT无符号整型
iint整型
llong长整型
wWORD双字节
dwDWORD四字节
ffloat浮点数
ddouble双精度数
chchar字符型
szchar[]以0结尾的字符串
crCOLORREFcolorref
pszLPCTSTRconstchar*字符串指针
pszLPTSTRchar*字符串指针
wndwindow窗口类
fnfunction函数
ppointer指针
ararray数组
lstlist链表
mapmap影射
eenum枚举
uunion联合
cstruct一般的结构体
cclass一般的类
注意：
1、有的类型可以组合以表示复杂的数据类型，即：
主数据类型+修饰类型
2、字符串指针char*、constchar*应使用LPTSTR、LPCTSTR替代
3、在类型前加const，命名约定不变
示例：
bytebyVal;BYTEbyVal;
boolbVal;BOOLbVal;
shortnVal;SHORTnVal;
UINTnVal;CUIntArrayarnVal;
intiVal;INTiVal;
longlVal;LONGiVal;ULONGlVal;
WORDwVal;WORDg_wVal;
DWORDdwVal;DWORDm_dwVal;
floatfVal;float&fVal;
doubledVal;double*pdVal;
charchVal;TCHARchVal;
charszName[5];TCHARszName[5]
COLORREFcrBackground;
LPCTSTRpszName;
LPTSTRpszName=newTCHAR[5];
CButtonwndOk;CToolBarwndTBar
WNDPROCpfnProc；
void*pUnknown;LPCTSTRpszKey;
CStringArrayarsVal;
CPtrListlstpVal;
CMapPtrToPtrmapVal;
enumEFileTypeeFileType;
unionUResvalcVal；
structSTreeDatacData；
classCStudentcXiaoMing；
void**ppVal；
CStringArrayarsNames；
LPCTSTRpszName；
LPCTSTRpszVal;LPTSTRpszVal;
Windows/VC++/MFC类型
sCString字符串
dcCDC设备环境对象
bmpCBitmap位图
penCPen画笔
brCBrush画刷
fntCFont字体
rgnCRgn区域
imglstCImageList图片列表
mnuCMenu菜单
ptCPoint点
vtvector向量
matmatrix矩阵
szCSize尺寸
rcCRect矩形
tmCTime时间
posPOSITION位置
hhandle句柄类
psmartpoint智能指针
CStringsFileName;
CClientDCdcMem;
CBitmapbmpLogo;
CPenpenRed;
CBrushbrBlue;
CFontfntArial;
CRgnrgnClip;
CImageListimglstIcons;
CMenumnuPopup;
CPointptPosition;POINTptMouse
vectorvtVal;
matrixmatTransform;
CSizeszNormal;
CRectrcClient;RECTrcDefault;
CTimetmCurrent;
POSITIONposStart;
HDChDC;HTREEITEMhParent;
_com_ptr_t<…>pInterface;
AutoCAD/ObjectARX类型
ptads_pointads点
entads_nameads实体
ssads_nameads选择集
matads_matrixads矩阵
dads_realads实数
rbstructresbufads链表
ptAcGePoint2d/3d点
vtAcGeVector2d/3d向量
scAcGeScale2d/3d比例
matAcGeMatrix2d/3d矩阵
extAcDbExtents边界
idAcDbObjectIdid
arAcArray数组
tolAcGeTol误差
ads_pointptStart;
ads_nameentLine;
ads_namessPickSet;
ads_matrixmatTransform;
ads_realdDistance;
structresbufrbXData;
AcGePoint3dptPosition;
AcGeVector2dvtDirection;
AcGeScale3dscZoom;
AcGeMatrix2dmatRotate
AcDbExtentsextView;
AcDbObjectIdidEnt;
AcDbVoidPtrArrayarpSubEntity;
AcGeToltolTemp;
5、函数
5.1、推荐使用动宾结构。
函数名应清晰反映函数的功能、用途，见名知意。
常见的函数命名开始：
Init_,Open_,Create_,Get_,Set_,Read_,Load_,Write_,Start_,Stop_,Check_,Test_,Fill_,Process_,Sort_,Do_,Select_,Is_,Exist_,
5.2、函数名每个单词或缩写的第一个字母必须大写。
正确：
voidDoJig（）
BOOLIsEmpty（）;
错误：
voidDO_JIG（）;
voidDo_Jig（）;
6、宏
6.1、使用单词或单词缩写，所有字母大写，单词之间使用_分隔。
6.2、在定义类似函数或变量的宏时例外，可参照函数或变量的命名规范。
示例：
#defineIsZero（dVal）（fabs（dVal）#defineg_rxRegistryAcRxRegistry:
:
cast（g_cGlobal.GetRegistry（））
7、文件名
7.1、文件名每个单词或缩写的第一个字母必须大写。
7.2、文件的命名也应达到见名知意，能够反映该文件所包含的内容。
7.3、如果文件中仅包含一个主要封装体的相关内容，则该文件名应使用封装体的名称。
8、控件ID和窗口对象
8.1、控件ID的命名应采用全部大写，各式为：
IDC_控件类型缩写_标识符。
8.2、控件窗口对象的命名应在窗口类型后加控件类型缩写。
常用控件命名列表：
文本StaticIDC_STC_XXXm_wndStcXxx
PictureIDC_PIC_XXXm_wndPicXxx
编辑框EditIDC_EDT_XXXm_wndEdtXxx
ComboBoxIDC_CMB_XXXm_wndCmbXxx
GroupBoxIDC_GRP_XXXm_wndGrpXxx
PushButtonIDC_BTN_XXXm_wndBtnXxx
RadioButtonIDC_RAD_XXXm_wndRadXxx
CheckBoxIDC_CHK_XXXm_wndChkXxx
ListBoxIDC_LST_XXXm_wndLstXxx
ScrollBarIDC_SCR_XXXm_wndScrXxx
SpinIDC_SPN_XXXm_wndSpnXxx
ProgressIDC_PRG_XXXm_wndPrgXxx
SliderIDC_SLD_XXXm_wndSldXxx
TabCtrlIDC_TAB_XXXm_wndTabXxx
ListCtrlIDC_LST_XXXm_wndLstXxx
TreeCtrlIDC_TRE_XXXm_wndTreXxx
AnimateIDC_ANM_XXXm_wndAnmXxx
二、编写规范
9、通则
9.1、尽量使用标准库函数和公共函数。
9.2、只能有唯一的声明和实现，提供包含使用。
9.3、不要随意定义全局变量，尽量使用局部变量。
9.4、全局变量和函数应放到命名空间中或静态类中或声明成静态函数。
9.5、程序结构清晰，简单易懂，单个函数的程序行数尽量短。
9.6、变量使用时要注意越界。
9.7、字符串操作应该支持处理UNICODE。
9.8、使用指针之前要做有效性判断。
10、源文件
10.1、在源文件（.h/.cpp）的开头应包含一段格式统一的说明，至少包括以下内容：
版权说明、文件名称、版本号、作者、生成时间、文件功能用途说明、维护记录。
//Copyright（C）,1998-2007,BeijingTangentEngineeringSoftwareCo.Ltd.
//=FileName:
文件名称
//=Version:
版本号
//=Author:
作者
//=Date:
创建时间
//=Description:
文件功能、用途等说明
//=Maintainers:
//版本号时间修改人修改内容
10.2、对于同时对应有.h和.cpp的文件，维护记录（Maintainers）应写在.h中，则在.cpp中可以省略。
10.3、在头文件（.h）中应提供为防止文件交叉包含的预编译宏，宏的定义应和文件名称一致，格式应为“__XXXX_H__”。
示例：
#if!
defined（__MYSAMPLE_H__）
#define__MYSAMPLE_H__
……
#endif//__MYSAMPLE_H__
10.4、对于无关的垃圾注释以及向导注释，一律清除，保持文件内容整洁。
11、封装体
11.1、在class/struct/union/enum等封装体声明之前，应包含有对该封装体的功能用途等有关的说明。
11.2、函数的声明应在变量的声明之前，不同的访问属性应按public/protected/private循序先后声明。
11.3、不被公开使用的声明不应放置在public块下，不需被继承的声明应放置在private块下。
11.4、一行只能声明一个成员变量或成员函数。
11.5、除了自动生成的Wizard代码，声明的变量和函数必须注释，且注释应该在其之前独占一行，并排列对齐。
11.6、对于enum的声明中，第一个成员应赋初始值，成员的注释可以放置在成员的声明之后。
11.7、struct/union中成员应使用简单数据类型
11.8、在仅有数据成员的封装体中允许成员变量不带m_前缀，在表达数据分量和使用频繁的情况下允许成员不带m_前缀（如点对象的分量x，y）。
11.9、对于不从其他封装体继承也确定不被继承的封装体，析构函数不应使用virtual修饰词。
11.10、封装体中元素的个数应适中并合理排布。
若结构中元素个数过多可考虑依据某种原则把元素组成不同的子结构，以减少原结构中元素的个数。
11.11、封装体的功能要单一，是针对一种事务的抽象；不要设计面面俱到，非常灵活的数据结构；不同封装体间的关系不要过于复杂；封装体的设计要考虑兼容和升级问题。
12、变量
12.1、变量应随时用随时声明，对代码效率有要求的循环体中，变量应声明在循环体外。
12.2、变量声明的同时应赋初值，析构或程序退出时判断释放所有变量。
12.3、一个变量只做一种应用，赋予一种意义。
12.4、对于作用域较大的变量和重要意义的变量应给予必要的注释。
12.5、指针型变量声明应一行只声明一个，不应与其他类型变量一起声明；声明中“*”号既可以紧接类型，也可以紧接变量名，不可以单独隔开。
12.6、不同类型的变量声明应各自独占一行，不可混到同一行。
13、函数
13.1、提高函数独立性，降低函数间的耦合度，一个函数应该只实现一个功能。
13.2、除非极其简单，否则应有注释说明，内容包括：
功能、入口/出口参数、返回值，必要时应该有维护记录。
//=FunctionName:
函数名称
//=Description:
函数功能、用途等说明
//=Return:
类型、返回值范围和意义
//=Parameters:
//类型变量名[IN/OUT]取值范围和说明
//=Maintainers:
//版本号时间修改人修改内容
13.3、不要将没有关联的语句放到一个函数中，避免函数中的不必要语句，防止程序中的垃圾代码。
更恰当：
//初始化矩形的长与宽
voidInitRect（）
{
rect.length=0;
rect.width=0;
}
//初始化点的坐标
voidInitPoint（）
{
point.x=10;
point.y=10;
}
不恰当：
voidInitVar（）
{
//初始化矩形长宽
rect.length=0;
rect.width=0;
//初始化点的坐标
point.x=10;
point.y=10;
}
13.4、函数功能是可以预测的，输入数据相同时就应该产生相同的输出。
13.5、函数的参数不允许在函数体内被修改的应加修饰词const，函数返回值不允许被修改的应加修饰词const，但是对于简单数据类型除外。
13.6、成员函数中，如果不涉及到对封装体数据成员修改的，应在函数最后加修饰词const。
13.7、参数传递中，如果参数包含大量数据时，应使用引用或指针方式传递。
13.8、函数返回值范围应充分考虑，并作全面处理。
13.9、要检查函数参数的合法性，对函数参数的合法性检查可以由函数的调用者负责，也可以由函数本身负责，同一项目应使用同一种检查方法，缺省是由函数调用者负责，在函数本身只使用断言宏为调试使用。
13.10、防止将函数的参数作为工作变量，函数调用不成功时，函数参数保证不被修改。
13.11、重复且独立性较强的代码应抽取成函数，功能不明确且较小的函数，特别是仅有一个上级函数调用它时，应考虑把它合并到上级函数中，而不必单独存在。
13.12、递归调用特别是函数间的递归调用（如A->B->C->A），影响程序的可理解性；递归调用一般都占用较多的系统资源（如栈空间）；递归调用对程序的测试有一定影响。
故除非为某些算法或功能的实现方便，应减少没必要的递归调用。
14、宏
14.1、宏定义表达式时，要注意完备的括号。
正确：
#defineAREA（dL,dH）（（dL）*（dH））
错误：
#defineAREA（dL,dH）dL*dH
14.2、将宏所定义的多条表达式放在大括号中。
14.3、使用宏时，不允许参数发生变化。
正确：
#defineSQUARE（iX）（（iX）*（iX））
intiVal=5;
intiRes=SQUARE（iVal）;
iVal++;
错误：
#defineSQUARE（iX）（（iX）*（iX））
intiVal=5;
intiRes=SQUARE（iVal++）;
14.4、宏定义中一般不使用缩
升级会员 