Visual-C++-编码规范.doc

Visual C++ 编码规范

1 引言
1.1 本文目
伴随越来越多项目需要Visual C++来编写, 为了便于各位项目经理、 程序员之前交流项目源程序, 而且确保源程序可读性, 特制订本《编程风格守则》, 本文读者为项目经理、 程序员, 以期在编码过程之中, 保持一致风格, 有利于软件工程项目推行。本文在编写上努力争取求大同、 存小异, 在编程风格上分为两类, 一类为强制风格, 意为一定需要遵守, 一类为推荐风格, 意为期望程序员在编码时根据这么风格。
1.2 背景
在软件工程领域, 源程序风格统一标志着可维护性、 可读性, 是软件项目一个关键组成部分。而现在还没有成文编码风格文档, 以致于很多时候, 程序员没有一个共同标准能够遵守, 编码风格各异, 程序可维护性差、 可读性也很差。
现在在编码上也有很多相关风格约定, 包含匈牙利命名法（一个变量取名措施）、 类MFC取名方法, 不过针对基于某种编译器项目完整编程风格守则, 现在还是比较少, 或者说比较零碎。
1.3 术语
系统: 指一个软件工程项目, 是一个系统;
项目: 指一个Visual C++项目;
Hungarian naming:
MFC: Microsoft Foundation Class Library;
1.4 参考资料
MSDN中相关MFC编写风格文章, 互联网上部分相关编写风格资料

2 概述
每位程序员都有自己编程风格, 因为每位程序员都有自己学习过程, 就象每个人个性一样, 所以编程风格是风彩各异、 百花齐放; 而从软件工程理论、 实践来看, 现代软件是多人合作结晶, 编程风格是否统一, 直接关系到软件项目可读性、 可维护性、 培训, 继而对软件开发成本有着直接关系, 编程风格一致, 软件项目易培训, 其它人员接手老项目时间缩短, 便于程序员之间交流。编程风格混乱, 则其它人员接手老项目时间增加, 同时伴随项目不停开发, 项目或者单个源程序文件内有着多个编程风格, 这么不利于整个项目开展以及程序员之间交流。
本文在参考业界已经有编码风格基础上, 描述了一个基于Visual C++编译器项目风格, 努力争取一个统一编程风格, 并从项目风格、 代码文件风格、 函数编写风格、 变量风格、 注释风格多个方面进行叙述。

3 项目风格
项目风格指是针对整个项目, 包含项目目录设置、 相关库文件设置、 Visual Studio集成环境设置等等习惯约定。具体有以下风格守则:
3.1 项目取名
在VC之中, 项目名为最终可实施文件名, 所以项目名最好以最终可实施文件名一致。
3.2 项目目录设置
为确保VC项目备份方便、 快捷, 可将全部该项目相关文件全部放到统一目录之下, 为每个项目在该目录之下建立一个目录, 项目之间公共部分建立在public目录之下, 项目所需要基础库依据所需要基础库数目分别建立不一样目录, 项目相关测试程序都统一放在TEST目录之下。下表显示了一个软件工程PSS系统目录设置表:
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

第三方公用模块
3.3 集成环境内项目目录设置
每个项目在VC编成编辑环境设置都采取相对路径设置, 不可采取绝对路径, 确保其备份到光盘设备后, 恢复到硬盘后, 不需要再过多设置就可直接编译。一样在用#include 语句时不要太多目录搜索, 以下所表示:
#include “../../../somehead.h”
改成:
#include “somehead.h”
然后在项目设置(Project Setting)中加入该头文件所在目录。
3.4 集成环境内模块划分
在VC项目集成环境之下, Project视图中FileView视图, 对于每个项目子模块都建立对应文件夹, 以对不一样子模块进行区分, 比如说PSS_mod1就可建立以下多个模块:
关键数据结构、 底层通用平台、 界面处理模块、 底层工作线程, 其中底层通用平台又可划分为CJ60开发包、 RCC通讯平台等等。

4 文件风格
4.1 文件生成
对于规范VC派生类, 尽可能用Class Wizard生成文件格式, 避免用手工制作头文件/实现文件。
不管是MFC源文件还是由App Wizard生成文件, 会发觉在这些类中有以下注释;
// Constructors
// Attributes
// Operations
// Overridables
// Implementation
每一次类都最少有一个//Implementation, 在不一样位置MFC做不一样处理, 在编写代码时最好与MFC这种风格一致。
4.2 文件头部注释
文件头部注释关键是表明该文件部分信息, 其格式以下:
///////////////////////////////////////////////////////////////////////////////////////////
// 文件名:
// 创建者:
// 创建时间:
// 内容描述:
///////////////////////////////////////////////////////////////////////////////////////////
4.3 空行约定
文件之中不得存在无规则空行, 比如说连续十个空行, 通常来讲函数与函数之前空行为2-3行, 在函数体内部, 在逻辑上独立两个函数块可合适空行, 通常为1-2行。
4.4 文件规格化功效键
源文件在编写完成时, Visual C++提供Alt+F8功效键, 进行文件规格化, 常使用该按键可使得文件保持规格化（注, Alt+F8功效键对连续两个CASE语句则会发生处理错误, 不能规格化）。

5 函数风格
5.1 函数注释
ClassWizard自动生成函数, 如消息响应函数, 则无须太多注释和解释;
对于自行编写函数, 若是系统关键函数, 则必需在函数实现部分上方标明该函数信息, 格式以下:
///////////////////////////////////////////////////////////////////////////////////////////
// 函数名:
// 编写者:
// 参考资料:
// 功 能:
// 输入参数:
// 输出参数:
// 备 注:
///////////////////////////////////////////////////////////////////////////////////////////
5.2 代码缩进
每一个嵌套函数块, 使用一个TAB缩进（能够设定为4个空格）, 大括号必需放在条件语句下一行, 单独成一行, 便于匹对:
if(condition)
{
while(condition)
{
}
}
5.3 函数命名
“动词”、 “动词+名词”, 如:
drawBox()

6 变量风格
变量尽可能采取匈牙利命名法, 同时结合VC标准; 通常情况下, 变量取名方法为:
<scope><prefix><qualifier>
相关项目全局变量必需用g_开始, 类组员变量用m_, 局部变量若函数较大则可考虑用l_用以显示说明其是局部变量。
前缀
类型
例子
g_
Global Variable
g_Servers
C
Class or structure
CDocument, CPrintInfo
m_
Member variable
m_pDoc, m_nCustomers

Visual C++常见前缀列表:
前缀
类型
描述
例子
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
0x1 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

7 注释风格
单行注释用双斜杠进行注释;
多行注释用/* */进行注释;
在封存某一版本源代码之中不得存在因为调试而留下大篇注释。
注释一行不要太多, 通常60个字符以内（确保VC集成编辑环境可见区域之内）, 如有超出, 则换行处理。