软件编码规范.doc

软件编码规范C+版 Ver1.1（草稿） 项目: 时间: 编号: 天正软件编码规范一、 命名规范1、 通则1.1、 在所有命名中，都应使用标准的英文单词或缩写，避免使用汉语拼音。1.2、 所有命名都应遵循达意原则，即名称应含义清晰、明确。1.3、 所有命名都不易过长，在可表达清晰的前提下越简洁越好。1.4、 所有命名都应尽量使用全称。1.5、 在类型名称特别复杂的时候，应使用typedef来定义别名。2、 标识符2.1、 标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。（较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写）如下单词的常用缩写application appargument argaverage avgblock blkbuffer bufcommand cmdcontrol ctrldatabase dbdelete deldescription descdialog dlgdictionary dictdimension dimdistance distdocument docentity entescape escflag flgincrease incinformation infolength lenlibrary libmanager mgrmemory memmessage msgobject objpassword pwdpicture picployline plinepointer ptrposition posrecord recreference refresource rscscreen scrserver srvsource srcsystem systemp tmptext txtversion verwindow wndVC+中常用控件缩写Animate aniCheck Box chkComboBox cmbEdit edtGroup Box grpListBox lstPicture picProgress prgPush Button btnRadio Button radScroll Bar sbSlider sldStatic stcTab Control tab14北京天正工程软件有限公司 Beijing Tangent Engineering Software Co. Ltd.2.2、 长的标识符应使用缩写来缩短长度，而特短的标识符应该避免使用缩写。更恰当：int iFlagHMODULE hLoadedSysRsc不恰当：int iFlgHMODULE hLoadedSystemResource2.3、 变量和封装体命名中单词或缩写的第一个字母应大写，其它字母小写，单词和单词之间直接连接，不得有其它字符。在宏定义中全部用大写，单词与单词之间必须用下划线连接。正确：TempResource#define REG_KEY错误：Temp_Resource temp_resourcetempresource#define Reg_Key2.4、 除了编译开关/头文件等特殊应用，应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义。2.5、 对于变量命名，禁止取单个字符（如i、j、k.），命名除了要有具体含义外，还能表明其变量类型、数据类型等，但i、j、k等作局部循环变量是允许的。2.6、 命名时，如果需要进一步分类时，分类属性应放在前面。正确：CListBox m_wndLstFonts;CComboBox m_wndCmbColors;错误：CListBox m_wndFontsLst;CComboBox m_wndColorsCmb;2.7、 命名中若使用特殊约定或缩写，则要有注释说明。（应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说明）2.8、 在命名规范中没有规定到的地方，才可以使用自己特有的命名风格，要自始至终保持一致，不可来回变化。2.9、 除非必要，不要用数字或较奇怪的字符来定义标识符。正确：#define EXAMPLE_TESTTestLockDriver错误：#define EXAMPLE_0Test1232.10、 在同一软件产品内，应规划好接口部分标识符的命名，防止编译、链接时产生冲突，可在普通标识基础上加上模块标识。示例：在TGRX模块中可定义为 CTGRxObject g_rxRegistry在TGDB模块中可定义为 CTGDbBlockRecord g_dbGlobal在TGGui模块中可定义为 CTGUiFrameWnd g_uiCmdMgr2.11、 命名规范必须与所使用的系统风格保持一致，并在同一项目中统一，比如有关STL的代码应使用STL中的全小写加下划线的风格，有关MFC的代码则使用大小写混排的方式。3、 封装体3.1、 采用前缀和以大写开头的英文单词或缩写组成，即：前缀 + 标识符。简写 类型 说明C class 类S struct 结构体E enum 枚举U union 联合体示例：class CTree ;struct SResBuf ;enum ESeekType ;union UResVal；4、 变量4.1、 变量命名应遵循匈牙利记法，即：前缀 + 类型 + 标识符。4.2、 前缀简写 类型 说明m_ class member 类的成员变量s_ static variable 静态全局变量g_ global variable 普通全局变量注意：1、 struct/union中的成员变量不加前缀，即：类型 + 标识符2、 const成员变量应使用k + 标识符3、 enum中的成员应使用k + 标识符示例：m_arsName m_lFilePoss_cConfig s_iLoopTimesg_hResouce g_sModuleNamestruct STreeDataHICON hTreeIcon;TCHAR szTreeName;；class CVector3dconst CVector3d kIdentity;const CVector3d kXAxis;enum EDirectionkLeft,kRight,;enum EErrorStatuskOk,kOutOfMemory,;4.3、 类型基本类型简写 类型 说明by byte 字节b bool 布尔型n short 短整型n UINT 无符号整型i int 整型l long 长整型w WORD 双字节dw DWORD 四字节f float 浮点数d double 双精度数ch char 字符型sz char 以0结尾的字符串cr COLORREF color refpsz LPCTSTR const char*字符串指针psz LPTSTR char*字符串指针wnd window 窗口类fn function 函数p pointer 指针ar array 数组lst list 链表map map 影射e enum 枚举u union 联合c struct 一般的结构体c class 一般的类注意：1、 有的类型可以组合以表示复杂的数据类型，即：主数据类型 + 修饰类型2、 字符串指针char*、const char*应使用LPTSTR、LPCTSTR替代3、 在类型前加const，命名约定不变示例：byte byVal; BYTE byVal;bool bVal; BOOL bVal;short nVal; SHORT nVal;UINT nVal; CUIntArray arnVal;int iVal; INT iVal;long lVal; LONG iVal; ULONG lVal;WORD wVal; WORD g_wVal;DWORD dwVal; DWORD m_dwVal;float fVal; float& fVal;double dVal; double* pdVal;char chVal; TCHAR chVal;char szName5; TCHAR szName5COLORREF crBackground;LPCTSTR pszName;LPTSTR pszName = new TCHAR5;CButton wndOk; CToolBar wndTBarWNDPROC pfnProc；void* pUnknown; LPCTSTR pszKey;CStringArray arsVal;CPtrList lstpVal;CMapPtrToPtr mapVal;enum EFileType eFileType;union UResval cVal；struct STreeData cData；class CStudent cXiaoMing；void* ppVal；CStringArray arsNames；LPCTSTR pszName；LPCTSTR pszVal; LPTSTR pszVal;Windows / VC+ / MFC类型s CString 字符串dc CDC 设备环境对象bmp CBitmap 位图pen CPen 画笔br CBrush 画刷fnt CFont 字体rgn CRgn 区域imglst CImageList 图片列表mnu CMenu 菜单pt CPoint 点vt vector 向量mat matrix 矩阵sz CSize 尺寸rc CRect 矩形tm CTime 时间pos POSITION 位置h handle 句柄类p smart point 智能指针CString sFileName;CClientDC dcMem;CBitmap bmpLogo;CPen penRed;CBrush brBlue;CFont fntArial;CRgn rgnClip;CImageList imglstIcons;CMenu mnuPopup;CPoint ptPosition; POINT ptMousevector vtVal;matrix matTransform;CSize szNormal;CRect rcClient; RECT rcDefault;CTime tmCurrent;POSITION posStart;HDC hDC; HTREEITEM hParent;_com_ptr_t pInterface;AutoCAD / ObjectARX类型pt ads_point ads点ent ads_name ads实体ss ads_name ads选择集mat ads_matrix ads矩阵d ads_real ads实数rb struct resbuf ads链表pt AcGePoint2d/3d 点vt AcGeVector2d/3d 向量sc AcGeScale2d/3d 比例mat AcGeMatrix2d/3d 矩阵ext AcDbExtents 边界id AcDbObjectId idar AcArray 数组tol AcGeTol 误差ads_point ptStart;ads_name entLine;ads_name ssPickSet;ads_matrix matTransform;ads_real dDistance;struct resbuf rbXData;AcGePoint3d ptPosition;AcGeVector2d vtDirection;AcGeScale3d scZoom;AcGeMatrix2d matRotateAcDbExtents extView;AcDbObjectId idEnt;AcDbVoidPtrArray arpSubEntity;AcGeTol tolTemp;5、 函数5.1、 推荐使用动宾结构。函数名应清晰反映函数的功能、用途，见名知意。常见的函数命名开始：Init_, Open_, Create_, Get_, Set_, Read_, Load_, Write_, Start_, Stop_, Check_, Test_, Fill_, Process_, Sort_, Do_, Select_, Is_, Exist_,5.2、 函数名每个单词或缩写的第一个字母必须大写。正确：void DoJig()BOOL IsEmpty();错误：void DO_JIG();void Do_Jig();6、 宏6.1、 使用单词或单词缩写，所有字母大写，单词之间使用_分隔。6.2、 在定义类似函数或变量的宏时例外，可参照函数或变量的命名规范。示例：#define IsZero(dVal) (fabs(dVal) B-C-A），影响程序的可理解性；递归调用一般都占用较多的系统资源（如栈空间）；递归调用对程序的测试有一定影响。故除非为某些算法或功能的实现方便，应减少没必要的递归调用。6、 宏6.1、 宏定义表达式时，要注意完备的括号。正确：#define AREA(dL, dH) (dL) * (dH)错误：#define AREA(dL, dH) dL * dH6.2、 将宏所定义的多条表达式放在大括号中。6.3、 使用宏时，不允许参数发生变化。正确：#define SQUARE(iX) (iX) * (iX)int iVal = 5;int iRes = SQUARE(iVal);iVal +;错误：#define SQUARE(iX) (iX) * (iX)int iVal = 5;int iRes = SQUARE(iVal+);6.4、 宏定义中一般不使用缩进，但是当宏定义比较复杂时可使用缩进。6.5、 对较复杂的断言宏加上明确的注释，不能用断言宏来检查最终产品肯定会出现且必须处理的错误情况。7、 排版7.1、 相对独立的程序块之间、函数间要有空行分开。7.2、 变量的定义尽可能放在最开始处，多态函数和功能相近的函数集中放在一起。7.3、 循环、分支代码，判断条件与执行代码不得在同一行上，且循环体外要加花括号“ ”。7.4、 程序块的分界符“”应独占一行，且位于同一列，同时与引用它们的语句左对齐。7.5、 不允许把多个短语句写在一行中，即一行只写一条语句。7.6、 声明变量时对齐变量名，并在定义时加以注释说明。7.7、 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如）后不应加空格。规则：1 逗号、分号只在后面加空格2 一些双目操作符如“=”、“+=”等前后应加空格3 一些单目操作符前后不加空格4 “-”、” . ”前后不加空格5 if、for、while、switch等与后面的括号间应加空格6 函数名与后面的括号不应加空格7 不要连续留两个以上空格示例：int iA, iB, iC; iA = iB + iC; iA = iB 2;iA *= 2; iA += iB;*piA = iA; iA+;pA-idK = iK; ptA.x = dX;if (iA + iB = 0)switch (eType)MessageBox(“Ok!”);7.8、 对齐和缩进以 TAB 为单位，不使用空格。1 个 TAB 为 4 个空格。下列情况，代码缩进一个 TAB：8 函数体相对函数名及“”“”9 if、else、for、while、do 等执行体10 class / struct / union / enum 成员下列情况，不必缩进：1 switch 之后的 case、default2 Public、protected、private关键字7.9、 划分新行1 长的语句（80字符）要分多行书写。2 长表达式要在低优先级操作符处划分新行。3 操作符放在新行之首。4 新行应有适当的缩进。示例：BOOL bFlag = (iTaskNo MAX_TASK_NUMBER) & (StateItemIsValid(stateitem) & (tableiTaskNo.iResult != 0);8、 代码8.1、 在代码中尽量不用具体的大小数值，定义成宏，便于以后维护。8.2、 在数据存取和接口代码中，为保证系统间的兼容性，不应使用int类型(因为不同系统之间的存储字节长度往往不同)，应使用long或short型。8.3、 在逻辑表达式中应将常量放在比较符之前，以减少误写造成的错误。更恰当：=误写成=时，编译报错LPCTSTR pszName = “Abc”if (NULL = pszName)不恰当：=误写成=时，不易察觉LPCTSTR pszName = “Abc”if (pszName = NULL)8.4、 少使用malloc、free、realloc，多用new、delete，new,delete是规范的C+语法，通用性强。8.5、 在数组数据存放个数无法确定的场合，应使用集合类。正确：CArray arClass;错误：Student pClass1000;8.6、 避免使用不易理解的数字，用有意义的标识（常量、枚举值或宏）来替代。在处理数据类型长度有关的代码中，不要用具体数值，而使用sizeof；文件名和路径声明中应使用MAX_PATH做长度。8.7、 注意运算符的优先级，尽量用括号明确表达式的操作顺序，避免使用默认优先级。更恰当：(iA | iB) & (iA & iC)不恰当：iA | iB & iA & iC8.8、 尽量用函数实现一些简单的功能，使功能明确化更恰当：int max (int iA, int iB) return (iA iB) ? iA : iB);iValue = max (iX, iY);不恰当：iValue = (iA iB) ? iA : iB;8.9、 防止下级作用域中的变量与上级作用域中的变量同名。8.10、 在写完左括号之后，建议立即写上右括号，在写完初始化代码后，建议立即写上清理代码，最后写中间处理代码，以防止遗漏。8.11、 源程序中关系较为紧密的代码应尽可能相邻，便于程序阅读和查找。8.12、 当进行数据类型强制转换时，其数据的意义、转换后的取值等都有可能发生变化，需要仔细考虑并作必要判断。尽量减少没有必要的数据类型默认转换与强制转换。8.13、 不要滥用goto语句。9、 注释9.1、 注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。9.2、 注释推荐使用中文，英文水平极佳者可以使用英文。但出于对维护人员的考虑，建议都使用中文。9.3、 为避免注释的嵌套混乱，所有注释都使用“/”开始。“/”不在行首的，“/”之前应全部使用TAB符，且至少有一个TAB符，之后应留有一个空格，相邻注释行应做适当对齐。9.4、 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。9.5、 避免在注释中使用缩写，特别是非常用缩写，在使用缩写时或之前，应对缩写进行必要的说明。9.6、 注释应与其描述的代码相近，对代码的注释应放在其上方，不可放在下方，并与其上面的代码用空行隔开，对enum体中成员和case语句的值做注释时可以放在右方。9.7、 注释与所描述内容进行同样的缩排。9.8、 避免在一行代码或表达式的中间插入注释。9.9、 在关系较为紧密的一段代码之前应给予注释，表达下面代码的功能、意图、算法等。10、 分支判断10.1、 BOOL / bool布尔值的判断正确：if (bFlag)if (!bFlag)错误：if (TRUE = bFlag)if (FALSE = bFlag)10.2、 float / double浮点值的判断正确：if (fabs(dValue1 dValue2) EPS)错误：if (dValue1 = dValue2)10.3、 指针的判断正确：if (NULL = pValue)不恰当：if (0 = pValue)10.4、 每个分支条件应该写注释加以说明。10.5、 对于case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。10.6、 在case语句中不应出现具体数值的标号，而应用宏或枚举类型代替。正确：#define BOX_TYPE 1switch (iType)case BOX_TYPE: break;不恰当：switch (iType)case 1: break;10.7、 一般地，if判断中if和else要齐全，switch分支中所有case和default要齐全。11、 循环11.1、 尽量减少循环体内的工作量，尽量减少循环层次。11.2、 在多重循环中，应该将最忙的循环放在最内层。11.3、 对代码效率有要求或循环体较小时，避免在循环体内声明变量，应将变量声明放在循环体之外；避免循环体内包含判断语句，应将循环体放在判断语句的代码块中。11.4、 循环判断条件应该有注释加以说明。12、 第三方代码和开发包(组件)12.1、 推荐参考或引用第三方的源代码或开发包(组件)。12.2、 引入的源代码或开发包(组件)必须成熟高效、具有源代码、没有版权问题，否则未经允许不得引入。12.3、 在引入第三方的源代码时，必须完全读懂和理解引入的代码，必须对源代码的编码规范进行修改，添加注释，以符合当前项目的编码规范要求。12.4、 在引入第三方开发包(组件)时，必须完整，并添加来源出处，增加详细的使用说明和接口说明。对第三方开发包(组件)，无须修改编码规范，必须独立编译，生成单独模块。三、 修改规范1、 通则1.1、 修改代码之前首先必须读懂代码。1.2、 应注释掉原来错误的代码，而不得随意删除，并写上错误原因。1.3、 在被修改的地方应写上修改信息，内容应包括：错误说明，修改方法、修改人、修改时间/ 错误说明/ 解决方法/ 修改人，修改时间1.4、 新加的代码应紧邻被注释掉的代码，以便查错和比较。1.5、 修改的错误信息应同时添加到更改记录文件的更改清单中。1.6、 不得随意修改或调整原来正确的代码，虽然原来的代码实现复杂或书写不规范。四、 项目管理规范1、 通则1.1、 工程中不起作用的文件或类应删除，工程目录下的非工程文件也应该移走，保持工程的清洁，避免混淆难于管理1.2、 在VC+环境下，建议将常用的头文件在StdAfx.h中包含，而在每个cpp开始处嵌入StdAfx.h。避免头文件的交叉引用，如果有交叉引用的，应适当使用类的声明。1.3、 将独立性比较强的模块抽出来，做成DLL、控件或COM组件，该模块可单独编写和测试，以增强其可重用性。1.4、 一个比较大的项目应留有一定的消息接口或插件接口等。1.5、 项目的版本控制要严格，版本格式为xx.xx.xx，必要时使用Build次数或日期。高版本尽量兼容低版本的用法、数据或协议。1.6、 工程的编译宏定义和工程参数设置应正确，每作一个新工程时应检查工程参数是否正确。2、 接口2.1、 同一个项目的导入和导出声明应统一，建议在独立的一个文件中声明，其他文件包含并使用。示例：#ifdef TG_EXPORT#define TG_API _declspec(dllexport)#else#define TG_API _declspec(dllimport)#endif / TG_EXPORTclass TG_API CMyExportClass;3、 编译3.1、 跟编译环境或版本有关的宏和lib库，建议在独立的一个文件中声明，避免设置到编译环境中，以防止混淆。示例：#if _ACAD_VER = 15#define SAVEAS_DWG SaveAsR15#pragma comment(lib, “AcDb15.lib”)#elif _ACAD_VER = 16#define SAVEAS_DWG SaveAsR16#pragma comment(lib, “AcDb16.lib”)#endif / _ACAD_VER3.2、 在编译环境设置中应尽量使用相对路径或路径宏（如$(ProjectName)、$(OutDir)等），以便更改一处后其他位置自动更改。3.3、 应排除编译过程中的所有警告，对于个别无法排除的警告要充分了解其产生的影响，确认它是正确的，应通过某种手段去掉告警信息。4、 目录结构4.1、 项目的文件应分类管理，应将必须的文件和编译的临时文