发信人: jinqiao (千王之王 ), 信区: SoftEng
标 题: Visual C++ 编程风格守则
发信站: 哈工大紫丁香 (2000年07月19日10:06:01 星期三), 站内信件
1 引言
1.1 本文目的
随着越来越多的项目需要Visual C++来编写，为了便于各位项目经理、程序员之前交流
项目源程序，并且保证源程序的可读性，特制定本《编程风格守则》，本文的读者为项
目经理、程序员，以期在编码过程之中，保持一致的风格，有利于软件工程项目的推行
。本文在编写上力求求大同、存小异，在编程风格上分为两类，一类为强制风格，意为
一定需要遵守，一类为推荐风格，意为希望程序员在编码时按照这样的风格。
1.2 背景
在软件工程领域，源程序的风格统一标志着可维护性、可读性，是软件项目的一个重要
组成部分。而目前还没有成文的编码风格文档，以致于很多时候，程序员没有一个共同
的标准可以遵守，编码风格各异，程序可维护性差、可读性也很差。
目前在编码上也有许多相关的风格约定，包括匈牙利命名法（一种变量的取名办法）、
类MFC取名方式，但是针对基于某种编译器的项目完整编程风格守则，目前还是比较少，
或者说比较零散。
1.3 术语
系统：指一个软件工程项目，是一个系统；
项目：指一个Visual C++项目；
Hungarian naming：
MFC：Microsoft Foundation Class Library；
1.4 参考资料
MSDN中有关MFC编写风格的文章，互联网上一些有关编写风格的资料（http://www.cs.c
lemson.edu/~kjhay/CpSc372/Week3/Week3.PPT）。
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编成编辑环境的设置都采用相对路径的设置，不可采用绝对路径，保证其
备份到光盘设备后，恢复到硬盘后，不需要再过多的设置就可直接编译。同样在用#inc
lude 语句时不要太多的目录搜索，如下所示：
#include “../../../somehead.h”
改成:
#include “somehead.h”
然后在项目设置(Project Setting)中加入该头文件的所在目录。
3.4 集成环境内的模块划分
在VC项目集成环境之下，Project视图中的FileView视图，对于每个项目的子模块都建立
相应的文件夹，以对不同的子模块进行区分，比如说PSS_mod1就可建立如下几个模块：
核心数据结构、底层通用平台、界面处理模块、底层工作线程，其中底层通用平台又可
划分为CJ60开发包、RCC通讯平台等等。
3.5 项目修改记录追踪
每一个VC项目必须存在Changes.Log，用以记载项目产生以来所有的改动，其格式必须如
下：
日期： 2000/4/28
修改人： 程旷
修改主题： 底层通讯由于MODEM响应代码而引起的不稳定现象
相关修改文件： CommLayer.cpp
修改内容详细描述：
另外充分利用Visual C++自动生成的Readme.txt文件来记载项目相关的信息。
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缩进（可以设定为3个空格），大括号必须放在条件
语句的下一行，单独成一行，便于匹对：
if(condition)
{
while(condition)
{
}
}
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
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
7 注释风格
单行注释用双斜杠进行注释；
多行注释用/* */进行注释；
在封存的某一版本的源代码之中不得存在由于调试而留下的大篇的注释。
注释一行不要太多，一般60个字符以内（保证VC集成编辑环境的可见区域之内），如有
超过，则换行处理
--
我的座右铭：
I Believe I can Fly!
I Believe I can Touch The Sky!
我坚信：
岁月似飞刀，刀刀催人老，
人老心不老，请服养命宝。
※ 来源:·哈工大紫丁香 bbs.hit.edu.cn·[FROM: 202.106.170.188]