OSSD研发规范-VC-v1.5.doc

文文 档档 编编 号号文档版本文档版本密级密级 OSSD-YFGF-VC-15 V 1.5 浪潮通信信息系统有限公司浪潮通信信息系统有限公司 OSSDOSSD 文档名称：文档名称：OSSD 研发规范研发规范 VC共共 页页 OSSDOSSD 研发规范研发规范 VCVC ( (仅供内部使用仅供内部使用) ) V 1.5.0 浪潮通信信息系统有限公司浪潮通信信息系统有限公司 2009-8-27 OSSD 研发规范 Page 2 of 13 版 本 历 史 版本/状态作者参与者起止日期备注 V1.5宋志钢2009-7-18 OSSD 研发规范 Page 3 of 13 目目 录录 1.工程设置规范工程设置规范.3 1.1.工程命名规则.3 1.2.工程的目录结构设置.3 1.3.集成环境内的项目目录设置.4 1.4.项目修改记录追踪.5 2.文件设置规范文件设置规范.5 2.1.文件生成.5 2.2.头部注释.5 2.3.文件规格化功能键.6 3.函数使用规范函数使用规范.6 3.1.函数名的约定.6 3.2.函数注释.6 4.变量命名规则变量命名规则.7 4.1.注释风格.11 4.2.常量命名和宏定义.11 5.代码规范代码规范.12 OSSD 研发规范 Page 4 of 13 1. 工程设置规范工程设置规范 1.1.1.1.工程命名规则工程命名规则 在 VC+之中，项目名为最后可执行文件名，所以项目名最好以最终的可执行文件名一致。 1.2. 工程的目录结构工程的目录结构设置设置 为保证 VC 项目的备份方便、快捷，将所有该项目有关的文件全部放到统一的目录之下， 为每个项目在该目录之下建立一个目录，项目之间的公共部分建立在 public 目录之下，项 目所需要的基础库根据所需要的基础库数目分别建立不同的目录，项目相关的测试程序都统 一放在 TEST 目录之下。 举例说明： Work 系统有两个模块 mod1 和 mod2，两个模块有一部分共用代码，在工程开发过程之中编写 了三个测试程序 TEST1、TEST2、TEST3，Work 系统开发过程之中用到了第三方公用模块 Third_Mod，则该系统的目录设置如下： 一级目录一级目录二级目录二级目录三级目录三级目录备注备注 Debug VC 集成环境生成的调试版本目录 Release VC 集成环境生成的发行版本目录 Res VC 集成环境生成的资源文件目录 Include 所属 mod1 的头文件 mod1 Source 所属 mod2 的头文件 Debug VC 集成环境生成的调试版本目录 Release VC 集成环境生成的发行版本目录 Res VC 集成环境生成的资源文件目录 Include 所属 mod1 的头文件 mod2 Source 所属 mod2 的头文件 Include Mod1 和 mod2 公用的头文件 Source Mod1 和 mod2 公用的源代码文件 PUBLIC Lib Mod1 和 mod2 公用的库文件 Test1 测试项目一 Test2 测试项目三 TEST Test3 测试项目三 WORKWORK Third_Mod 第三方公用模块 OSSD 研发规范 Page 5 of 13 1.3.1.3.集成环境内的项目目录设置集成环境内的项目目录设置 每个项目在 VC 编成编辑环境的设置都采用相对路径的设置，不可采用绝对路径，保证其 备份到光盘设备后或恢复到硬盘时， 不需要再过多的设置就可直接编译。同样在用#include 语句时不要太多的目录搜索，如下所示： #include “/somehead.h” 改成: #include “headfile.h“ 或#incldue “dir/headfile.h“ 并注意#include “headfile.h“与#include 的区别 然后在项目设置(Project Setting)中加入该头文件的所在目录。 1.4.1.4.项目修改记录追踪项目修改记录追踪 每一个 VC 项目必须存在 Changes.Log，用以记载项目产生以来所有的改动，其格式必须如 下： 日期： 2009-08-25 修改人： * 修改原因： 相关修改的文件： 修改内容详细描述： 另外可充分利用 Visual C+自动生成的 Readme.txt 文件来记载项目相关的信息。 2. 文件设置规范文件设置规范 2.1. 文件生成文件生成 文件名的语义应该能概括表达本文件所包含函数主要实现什么功能。文件名用小写英文字母 表达，严禁使用中文；对于几个单词组合表达的文件名，单词之间用_符号分开。文件名的 后缀定义： a VC 自动生成的源文件和头文件后缀分别为：*.cpp 和.h。 b 其他源文件和头文件后缀分别为：*.cxx 和*.hxx。 对于规范的 VC 派生类，尽量用 Class Wizard 生成文件格式，尽量避免用手工制作头文 OSSD 研发规范 Page 6 of 13 件/实现文件。 / Constructors /构造 / Attributes /属性 / Operations /操作, / Overridables /可重载的 / Implementation /实现 每一次类都至少有一个/Implementation，在不同的位置 MFC 做不同的处理，在编写代码 时最好 与 MFC 这种风格一致。 2.2. 头部注释头部注释 文件头部注释主要是表明该文件的一些信息，其格式如下： / / 文件名 : / 版本 : / 目的及主要功 : / 创建日期 : / 修改日期 : / 作者 : / 修改者 : / 2.3. 文件规格化功能键文件规格化功能键 源文件在编写完毕时，Visual C+提供 Alt+F8 功能键，进行文件规格化，常使用该按键可 使得文件保持规格化（注，Alt+F8 功能键对连续两个 CASE 语句则会发生处理错误，不能规 格化）。 3. 函数使用规范函数使用规范 3.1. 函数名的约定函数名的约定 函数名的语义应该能反映函数实现的功能。 对于对于 api 函数的命名规则为：函数的命名规则为： a 函数一律以 api_lm_开头；lm 表示此函数为 lonicera-mda 子系统的函数， pdm 模块的 函数名以 api_lp_开头。 OSSD 研发规范 Page 7 of 13 b 后面的命名以函数语义为基准，如创建一点的函数完整的函数名为 api_lm_ceate_point()。 对于对于 DI 函数的命名规则：函数的命名规则： a 函数名=lm_+（函数语义）。 b 对于几个单词组合表达的函数名，各单词之间以_符号分开。 3.2. 函数注释函数注释 ClassWizard 自动生成的函数，如消息响应函数，则不必太多的注释和解释； 对于自行编写的函数，若是系统关键函数，则须在函数实现部分的上方标明该函数的信息， 格式如下： /= / 函 数 名： / 功能描述： / 输入参数： / 输出参数： / 创建日期： / 修改日期： / 作 者： / 附加说明： /= 4. 变量命名规则变量命名规则 变量尽量采用匈牙利命名法，同时结合 VC 的原则；一般情况下，变量的取名方式为： + + 。 范围前缀_，类型前缀_，限定词。 特殊的类型命名特殊的类型命名, ,前缀表示：前缀表示： 类、接口 前缀前缀类型类型例子例子备注备注 LmLmClass LmObject I I Interface 接口 IUnknown 表示类型本身 不与范围前缀结合使用 注：类名前缀改为 Lm，对于非全局的类最好有语义表示其所属模块。类的实例命名与类名大 致相同，只是类名语义表示类的通用含义，而类名表示此实例的具体语义。如类名 LmSketPoint 表示草图点的类定义，而它的两个实例 _StartPoint,_EndPoint 分别代表起点 和终点的语义。类的实例命名带上前缀_。 特殊约定： a MouseTool 的派生类的前缀为_Mt. OSSD 研发规范 Page 8 of 13 b 对话框类的前缀为 CDlg. c 橡皮条类的前缀为_Rb. 范围前缀范围前缀: : 前缀前缀类型类型例子例子备注备注 g_g_ 全局作用域g_Servers m_m_ 成员变量m_pDoc, l_l_ 局部作用域 l_strName 少用 注注：编程时尽量少用全程变量，对于全程变量还应在类型前缀后加上如下关键字： 特征模块 ： Fea 草图模块 ： Sket 装配模块 ： Asm 工程图模块 ： Lay 曲面模块 ： Surf 界面模块 ： Ui 类型前缀类型前缀 1 1、: : 常用的一般数据类型的前缀表示(这只是一部分) 前缀前缀类型类型内存规格描述内存规格描述例子例子 chchar8-bit characterchGrade chTCHAR16-bit character if _UNICODE is definedchName bBOOLBoolean valuebEnabled nintInteger (size dependent on operating system) nLength nUINTUnsigned value (size dependent on operating system) nLength wWORD16-bit unsigned valuewPos lLONG32-bit signed integerlOffset dwDWORD32-bit unsigned integerdwRange p*Ambient memory model pointerpDoc lpFAR*Far pointerlpDoc lpszLPSTR32-bit pointer to character stringlpszName lpszLPCSTR32-bit pointer to constant character stringlpszName lpszLPCTSTR32-bit pointer to constant character string if _UNICODE is defined lpszName hhandleHandle to Windows objecthWnd lpfn(*fn)()callbackFar pointer to CALLBACK functionlpfnAbort 常用常用 WindowsWindows 对象名称缩写：对象名称缩写： OSSD 研发规范 Page 9 of 13 这些名称缩写很多情况下可直接使用，直接作变量的名称。 Windows 对象对象例子变量例子变量MFC 类类例子对象例子对象 HWNDhWnd;CWnd*pWnd; HDLGhDlg;CDialog*pDlg; HDChDC;CDC*pDC; HGDIOBJhGdiObj;CGdiObject*pGdiObj; HPENhPen;CPen*pPen; HBRUSHhBrush;CBrush*pBrush; HFONThFont;CFont*pFont; HBITMAPhBitmap;CBitmap*pBitmap; HPALETTEhPalette;CPalette*pPalette; HRGNhRgn;CRgn*pRgn; HMENUhMenu;CMenu*pMenu; HWNDhCtl;CStatic*pStatic; HWNDhCtl;CButton*pBtn; HWNDhCtl;CEdit*pEdit; HWNDhCtl;CListBox*pListBox; HWNDhCtl;CComboBox*pComboBox; 其它的宏定义其它的宏定义 建议全用大写字母，用下划线分隔。 Visual C+常用宏定义命名列表： 前缀前缀符号类型符号类型符号例子符号例子范围范围 IDR_标识多个资源共享 的类型 IDR_MAINFRAME1 to 0x6FFF IDD_对话框资源 (Dialog) IDD_SPELL_CHECK1 to 0x6FFF HIDD_基于对话框的上下 文帮助(Context Help) HIDD_SPELL_CHECK0x20001 to 0x26FF IDB_位图资源(Bitmap)IDB_COMPANY_LOGO1 to 0x6FFF IDC_光标资源(Cursor)IDC_PENCIL1 to 0x6FFF IDI_图标资源(Icon)IDI_NOTEPAD1 to 0x6FFF ID_IDM_工具栏或菜单栏的 命令项 ID_TOOLS_SPELLING0x8000 to 0xDFFF HID_命令上下文帮助 (Command Help context) HID_TOOLS_SPELLING0x18000 to 0x1DFFF IDP_消息框提示文字资 源 IDP_INVALID_PARTNO8 to 0xDFFF HIDP_消息框上下文帮助HIDP_INVALID_PARTNO0x30008 to OSSD 研发规范 Page 10 of 13 (Message-box Help context) 0x3DFFF IDS_字符串资源 (String) IDS_COPYRIGHT1 to 0x7FFF IDC_对话框内的控制资 源(Control) IDC_RECALC8 to 0xDFFF 4.1. 注释风格注释风格 单行注释用双斜杠进行注释； 多行注释用/* */进行注释； 在封存的某一版本的源代码之中不得存在由于调试而留下的大篇的注释。 注释一行不要太多，一般 60 个字符以内（保证 VC 集成编辑环境的可见区域之内），如有超 过，则换行处理。 4.2. 常量命名和宏定义常量命名和宏定义 常量和宏定义必须具有一定的实际意义; 常量和宏定义在#include 和函数定义之间; 常量和宏定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一 条定义的右侧必须有一简单的注释,说明其作用; 资源名字定义格式: 菜单:IDM_XX 或者 CM_XX 位图:IDB_XX 对话框:IDD_XX 字符串:IDS_XX DLGINIT:DIALOG_XX ICON:IDR_XX 结构体命名 结构体类型命名必须全部用大写字母,原则上前面以下划线开始;结构体变量命名必须用大小 写字母组合，第一个字母必须使用大写字母,必要时可用下划线间隔。对于私有数据区，必须 注明其所属的进程。全局数据定义只需注意其用途。 示例如下： typedef struct char szProductName20; char szAuthor20; OSSD 研发规范 Page 11 of 13 char szReleaseDate16; char szVersion10; unsigned long MaxTables; unsigned long UsedTables; DBS_DATABASE; DBS_DATABASE GdataBase; 控件的命名： 用小写前缀表示类别： fm 窗口 cmd 按钮 cob 下拉式列表框 txt 文本输入框 lab 标签 img 图象 pic picture grd Grid，网格 scr 滚动条 lst 列表框 frm fram 5. 代码规范代码规范 a)除非极其简单，否则对函数应有注释说明。内容包括：功能、入口/出口参数，必要时还 可有备注或补充说明。还是好习惯 b)每列代码的长度推荐为 80 列，最长不得超过 120 列；折行以对齐为准。太宽了，我 的限制是 60 列，因为文本方式下屏幕一共 80 列，如果你用 BC 这一类的编辑器，窗口 边框等又要占据一定空间，所以 80 列太宽 c)循环、分支代码，判断条件与执行代码不得在同一行上。 d)指针的定义，* 号既可以紧接类型，也可以在变量名之前。 例：可写做：int* pnsize; 也可写做：int *pnsize; 但不得写做：int * pnsize; 建议采用第二种，除非附加另外一条规定：一次只声明一个变量，否则就会让人混淆， 比如： int* a, b; 看起来 b 好像也是个指针，其实不是。 e) 在类的成员函数内调用非成员函数时，在非成员函数名前建议加上“:“。 f) 函数入口参数有缺省值时，应注释说明。每个变量写一行，必要时加上/*in, out*/注释 g)else if 必须写在一行。应该尽量避免 else if 这样的结构 h)与、有关的各项规定： OSSD 研发规范 Page 12 of 13 、应独占一行。在该行内可有注释。 必须另起一行， 之后的代码必须缩进一个 Tab。与必须在同一 列上。 在循环、分支之后若只有一行