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，则该系统的目录设置如下：一级目录二级目录三级目录备注WORKPSS_mod1DebugVC集成环境生成的调试版本目录ReleaseVC集成环境生成的发行版本目录ResVC集成环境生成的资源文件目录Include所属mod1的头文件Source所属mod2的头文件PSS_mod2DebugVC集成环境生成的调试版本目录ReleaseVC集成环境生成的发行版本目录ResVC集成环境生成的资源文件目录Include所属mod1的头文件Source所属mod2的头文件PUBLICIncludeMod1和mod2公用的头文件SourceMod1和mod2公用的源代码文件LibMod1和mod2公用的库文件TESTPSS_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的原则；一般情况下，变量的取名方式为：有关项目的全局变量必须用g_开始，类成员变量用m_，局部变量若函数较大则可考虑用l_用以显示说明其是局部变量。前缀 类型 例子 g_Global Variable g_Servers CClass or structure CDocument, CPrintInfo m_Member variable m_pDoc, m_nCustomers Visual C+常用前缀列表：前缀 类型 描述 例子 chchar8-bit character chGrade chTCHAR16-bit character if _UNICODE is defined chName bBOOLBoolean value bEnabled nintInteger (size dependent on operating system) nLength nUINTUnsigned value (size dependent on operating system) nLength wWORD16-bit unsigned value wPos lLONG32-bit signed integer lOffset dwDWORD32-bit unsigned integer dwRange p*Ambient memory model pointer pDoc lpFAR*Far pointer lpDoc lpszLPSTR32-bit pointer to character string lpszName lpszLPCSTR32-bit pointer to constant character string lpszName lpszLPCTSTR32-bit pointer to constant character string if _UNICODE is defined lpszName hhandleHandle to Windows object hWnd lpfn(*fn)()callbackFar pointer to CALLBACK function lpfnAbort Windows对象名称缩写：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_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