VC源代码编码约定 |
1 项目风格
1.1 项目取名
在VC之中,项目名为最后可执行文件名,所以项目名最好以最终的可执行文件名一致。
1.2 项目目录设置
为保证VC项目的备份方便、快捷,将所有该项目有关的文件全部放到统一的目录之下,为每个项目在该目录之下建立一个目录,项目之间的公共部分建立在public目录之下,项目所需要的基础库根据所需要的基础库数目分别建立不同的目录,项目相关的测试程序都统一放在TEST目录之下。下表显示了一个软件工程PSS系统的目录设置表:
PSS系统有两个模块PSS_mod1和PSS_mod2,两个模块有一部分共用代码,在工程开发过程之中编写了三个测试程序PSS_TEST1、 PSS_TEST2、PSS_TEST3,PSS系统开发过程之中用到了第三方公用模块Third_Mod,则该系统的目录设置如下:
一级目录 | 二级目录 | 三级目录 | 备注 |
WORK | PSS_mod1 | Debug | VC集成环境生成的调试版本目录 |
Release | VC集成环境生成的发行版本目录 | ||
Res | VC集成环境生成的资源文件目录 | ||
Include | 所属mod1的头文件 | ||
Source | 所属mod2的头文件 | ||
PSS_mod2 | Debug | VC集成环境生成的调试版本目录 | |
Release | VC集成环境生成的发行版本目录 | ||
Res | VC集成环境生成的资源文件目录 | ||
Include | 所属mod1的头文件 | ||
Source | 所属mod2的头文件 | ||
PUBLIC | Include | Mod1和mod2公用的头文件 | |
Source | Mod1和mod2公用的源代码文件 | ||
Lib | Mod1和mod2公用的库文件 | ||
TEST | PSS_Test1 | 测试项目一 | |
PSS_Test2 | 测试项目三 | ||
PSS_Test3 | 测试项目三 | ||
Third_Mod |
| 第三方公用模块 |
1.3 集成环境内的项目目录设置
每个项目在VC编成编辑环境的设置都采用相对路径的设置,不可采用绝对路径,保证其备份到光盘设备后或恢复到硬盘时, 不需要再过多的设置就可直接编译。同样在用#include 语句时不要太多的目录搜索,如下所示:
#include “../../../somehead.h”
改成:
#include "headfile.h"
或#incldue "dir/headfile.h"
并注意#include "headfile.h"与#include <headfile.h>的区别
然后在项目设置(Project Setting)中加入该头文件的所在目录。
1.4 项目修改记录追踪
每一个VC项目必须存在Changes.Log,用以记载项目产生以来所有的改动,其格式必须如下:
日期: 2000/4/28
修改人: **
修改主题:
相关修改文件: hello.cpp
修改内容详细描述:
另外可充分利用Visual C++自动生成的Readme.txt文件来记载项目相关的信息。
2 文件风格
2.1 文件生成
文件名的语义应该能概括表达本文件所包含函数主要实现什么功能。文件名用小写英文字母表达,严禁使用中文;对于几个单词组合表达的文件名,单词之间用_符号分开。
文件名的后缀定义:
a. VC自动生成的源文件和头文件后缀分别为:*.cpp和.h。
b. 其他源文件和头文件后缀分别为:*.cxx和*.hxx。
对于规范的VC派生类,尽量用Class Wizard生成文件格式,避免用手工制作头文件/实现文件。
// Constructors //构造
// Attributes //属性, 品质, 特征, 加于, 归结
// Operations //运转, 操作, 实施, 作用, 业务, 工作, 手术, 军事行动
// Overridables //可重载的
// Implementation //实现
每一次类都至少有一个//Implementation,在不同的位置MFC做不同的处理,在编写代码时最好
与MFC这种风格一致。
2.2 文件头部注释
文件头部注释主要是表明该文件的一些信息,其格式如下:
///
// 文件名 : mange_fun.cxx
// 版本 :
// 目的及主要功 : 系统参数的设定
// 创建日期 : 1999.09.14
// 修改日期 :
// 作者 : ***
// 修改者 :
2.3 文件规格化功能键
源文件在编写完毕时,Visual C++提供Alt+F8功能键,进行文件规格化,常使用该按键可使得文件保持规格化(注,Alt+F8功能键对连续两个CASE语句则会发生处理错误,不能规格化)。
3 函数风格
3.1 函数名的约定。
函数名的语义应该能反映函数实现的功能。
对于api函数的命名规则为:
a. 函数一律以api_lm_开头;lm表示此函数为lonicera-mda子系统的函数, pdm模块的函数名以api_lp_开头。
b. 后面的命名以函数语义为基准,如创建一点的函数完整的函数名为api_lm_ceate_point()。
对于DI函数的命名规则:
a. 函数名=lm_+(函数语义)。
b. 对于几个单词组合表达的函数名,各单词之间以_符号分开。
3.2 函数注释
ClassWizard自动生成的函数,如消息响应函数,则不必太多的注释和解释;
对于自行编写的函数,若是系统关键函数,则须在函数实现部分的上方标明该函数的信息,格式如下:
//======================================================================
// 函 数 名:InsureHasOutputInfo
// 功能描述:确保有适当的输出信息
// 输入参数:nProductID:相应的产品ID
// 输出参数:void
// 创建日期:00-2-21
// 修改日期:00-2-21
// 作 者:***
// 附加说明:
//======================================================================
3.3 代码缩进
每一个嵌套的函数块,使用一个TAB缩进(可以设定为3个空格),大括号必须放在条件语句的下一行,单独成一行,便于匹对反大括号应该在单独的一行,在大多数情况下反扩号应有注释内容。举例如下:
if(condition1)
{
while(condition2)
{
…..
…..
}//end while(condition2)
}//end if (condition1)
或者
if(condition1){
while(condition2){
….
….
}//end while(condition2)
}//end if(conditionl)
3 .4 其它规范
1、 每个源文件包括的函数体不应该多于20个,每个函数体不应该超过120行原代码。
2、 函数的输入参数不多于5个,输出参数不多于5个。
3、 对于超过3句以上的语句反复调用,应封装为函数调用。
4、 尽量避免三层以上的嵌套循环 ;尽量减少程序的 if语句;少用诸如I*=b、A=C+D*B++等语义难懂的语句。
5、 充分利用C++的思想,真正意义上地用C++语言编程;对类扩充成员函数。
4 变量风格
变量尽量采用匈牙利命名法,同时结合VC的原则;一般情况下,变量的取名方式为:
<scope_> + <prefix_> + <qualifier>。
范围前缀_,类型前缀_,限定词。
特殊的类型命名,前缀表示:
类、接口
前缀 | 类型 | 例子 | 备注 |
Lm | Class | LmObject | 表示类型本身 |
I | Interface 接口 | IUnknown |
注:类名前缀改为Lm,对于非全局的类最好有语义表示其所属模块。类的实例命名与类名大致相同,只是类名语义表示类的通用含义,而类名表示此实例的具体语义。如类名LmSketPoint表示草图点的类定义,而它的两个实例 _StartPoint,_EndPoint分别代表起点和终点的语义。类的实例命名带上前缀_。
特殊约定:
a. MouseTool的派生类的前缀为_Mt.
b. 对话框类的前缀为CDlg.
c. 橡皮条类的前缀为_Rb.
范围前缀:
前缀 | 类型 | 例子 | 备注 |
g_ | 全局作用域 | g_Servers |
|
m_ | 成员变量 | m_pDoc, | |
l_ | 局部作用域 | l_strName | 少用
|
注:编程时尽量少用全程变量,对于全程变量还应在类型前缀后加上如下关键字:
特征模块 : Fea
草图模块 : Sket
装配模块 : Asm
工程图模块 : Lay
曲面模块 : Surf
界面模块 : Ui
类型前缀 1、:
常用的一般数据类型的前缀表示(这只是一部分)
前缀 | 类型 | 内存规格描述 | 例子 |
ch | char | 8-bit character | chGrade |
ch | TCHAR | 16-bit character if _UNICODE is defined | chName |
b | BOOL | Boolean value | bEnabled |
n | int | Integer (size dependent on operating system) | nLength |
n | UINT | Unsigned value (size dependent on operating system) | nLength |
w | WORD | 16-bit unsigned value | wPos |
l | LONG | 32-bit signed integer | lOffset |
dw | DWORD | 32-bit unsigned integer | dwRange |
p | * | Ambient memory model pointer | pDoc |
lp | FAR* | Far pointer | lpDoc |
lpsz | LPSTR | 32-bit pointer to character string | lpszName |
lpsz | LPCSTR | 32-bit pointer to constant character string | lpszName |
lpsz | LPCTSTR | 32-bit pointer to constant character string if _UNICODE is defined | lpszName |
h | handle | Handle to Windows object | hWnd |
lpfn | (*fn)() | callbackFar pointer to CALLBACK function | lpfnAbort |
常用Windows对象名称缩写:
这些名称缩写很多情况下可直接使用,直接作变量的名称。
Windows 对象 | 例子变量 | MFC类 | 例子对象 |
HWND | hWnd; | CWnd* | pWnd; |
HDLG | hDlg; | CDialog* | pDlg; |
HDC | hDC; | CDC* | pDC; |
HGDIOBJ | hGdiObj; | CGdiObject* | pGdiObj; |
HPEN | hPen; | CPen* | pPen; |
HBRUSH | hBrush; | CBrush* | pBrush; |
HFONT | hFont; | CFont* | pFont; |
HBITMAP | hBitmap; | CBitmap* | pBitmap; |
HPALETTE | hPalette; | CPalette* | pPalette; |
HRGN | hRgn; | CRgn* | pRgn; |
HMENU | hMenu; | CMenu* | pMenu; |
HWND | hCtl; | CStatic* | pStatic; |
HWND | hCtl; | CButton* | pBtn; |
HWND | hCtl; | CEdit* | pEdit; |
HWND | hCtl; | CListBox* | pListBox; |
HWND | hCtl; | CComboBox* | pComboBox; |
其它的宏定义
建议全用大写字母,用下划线分隔。 Visual C++常用宏定义命名列表:
前缀 | 符号类型 | 符号例子 | 范围 |
IDR_ | 标识多个资源共享的类型 | IDR_MAINFRAME | 1 to 0x6FFF |
IDD_ | 对话框资源(Dialog) | IDD_SPELL_CHECK | 1 to 0x6FFF |
HIDD_ | 基于对话框的上下文帮助(Context Help) | HIDD_SPELL_CHECK | 0x20001 to 0x26FF |
IDB_ | 位图资源(Bitmap) | IDB_COMPANY_LOGO | 1 to 0x6FFF |
IDC_ | 光标资源(Cursor) | IDC_PENCIL | 1 to 0x6FFF |
IDI_ | 图标资源(Icon) | IDI_NOTEPAD | 1 to 0x6FFF |
ID_IDM_ | 工具栏或菜单栏的命令项 | ID_TOOLS_SPELLING | 0x8000 to 0xDFFF |
HID_ | 命令上下文帮助(Command Help context) | HID_TOOLS_SPELLING | 0x18000 to 0x1DFFF |
IDP_ | 消息框提示文字资源 | IDP_INVALID_PARTNO | 8 to 0xDFFF |
HIDP_ | 消息框上下文帮助(Message-box Help context) | HIDP_INVALID_PARTNO | 0x30008 to 0x3DFFF |
IDS_ | 字符串资源(String) | IDS_COPYRIGHT | 1 to 0x7FFF |
IDC_ | 对话框内的控制资源(Control) | IDC_RECALC | 8 to 0xDFFF |
5 注释风格
单行注释用双斜杠进行注释;
多行注释用/* */进行注释;
在封存的某一版本的源代码之中不得存在由于调试而留下的大篇的注释。
注释一行不要太多,一般60个字符以内(保证VC集成编辑环境的可见区域之内),如有超过,则换行处理。