白盒测试 [代码规范] [C++] 一

文件结构

文件头注释

所有C++的源文件均必须包含一个规范的文件头，文件头包含了该文件的名称、功能概述、作者、版权和版本历史信息等内容。标准文件头的格式为：

　

 

　

如果该文件有其它需要说明的地方，还可以专门为此扩展一节 ，节与节之间用长度为80的“=”带分割：

 

每行注释的长度都不应该超过80个半角字符。还要注意缩进和对齐，以利阅读。

注意：将多线程和异常时安全性描述放在文件头，而不是类或者函数注释中，是为了体现以下设计思想：同一个模块中的界面，其各方面的操作方式和使用风格应该尽量保持一致。

关于文件头的完整例子，请参见：文件头例子

关于文件头的模板，请参见：文件头注释模板

　

头文件

头文件通常由以下几部分组成：

　

文件头注释

每个头文件，无论是内部的还是外部的，都应该由一个规范的文件头注释作为开始。

　

预处理块

为了防止头文件被重复引用，应当用ifndef/define/endif结构产生预处理块。

　

函数和类/结构的声明等

声明模块的接口

　

需要包含的内联函数定义文件（如果有的话）

如果类中的内联函数较多，或者一个头文件中包含多个类的定义（不推荐），可以将所有内联函数定义放入一个单独的内联函数定义文件中，并在类声明之后用“#include”指令把它包含进来。

头文件的编码规则：

引用文件的格式

用 #include <filename.h> 格式来引用标准库和系统库的头文件（编译器将从标准库目录开始搜索）。

用 #include "filename.h" 格式来引用当前工程中的头文件（编译器将从该文件所在目录开始搜索）。

　

分割多组接口（如果有的话）

如果在一个头件中定义了多个类或者多组接口（不推荐），为了便于浏览，应该在每个类/每组接口间使用分割带把它们相互分开。

关于头文件的完整例子，请参见：头文件例子

　

内联函数定义文件

如上所述，在内联函数较多的情况下，为了避免头文件过长、版面混乱，可以将所有的内联函数定义移到一个单独的文件中去，然后再用#include指令将它包含到类声明的后面。这样的文件称为一个内联函数定义文件。

按照惯例，应该将这个文件命名为“filename.inl”，其中“filename”与相应的头文件和实现文件相同。

内联函数定义文件由以下几部分组成：

文件头注释

每内联函数定义文件都应该由一个规范的文件头注释作为开始

内联函数定义

内联函数的实现体

内联函数定义文件的编码规则：

分割多组接口（如果有的话）

如果在一个内联函数定义文件中定义了多个类或者多组接口的内联函数（不推荐），必须在每个类/每组接口间使用分割带把它们相互分开。

　

文件组成中为什么没有预处理块？

与头文件不同，内联函数定义文件通常不需要定义预处理块，这是因为他们总是被包含在与其相应的头文件预处理块内。

关于内联函数定义文件的完整例子，请参见：内联函数定义文件例子

　

实现文件

实现文件包含所有数据和代码的实现体。实现文件的格式为：

　

文件头注释

每个实现文件都应该由一个规范的文件头注释作为开始

　

对配套头文件的引用

引用声明了此文件实现的类、函数及数据的头文件

　

对一些仅用于实现的头文件的引用（如果有的话）

将仅与实现相关的接口包含在实现文件里（而不是头文件中）是一个非常好的编程习惯。这样可以有效地屏蔽不应该暴露的实现细节，将实现改变对其它模块的影响降低到最少 。

　

程序的实现体

数据和函数的定义

实现文件的编码规则：

分割每个部分

在本地（静态）定义和外部定义间，以及不同接口或不同类的实现之间，应使用分割带相互分开。

关于实现文件的完整例子，请参见：实现文件例子

　

文件的组织结构

由于项目性质、规模上存在着差异，不同项目间的文件组织形式差别很大。但文件、目录组织的基本原则应当是一致的：使外部接口与内部实现尽量分离；尽可能清晰地表达软件的层次结构……

为此提供两组典型项目的文件组织结构范例作为参考：

功能模块/库的文件组织形式

显而易见，编写功能模块和库的主要目的是为其它模块提供一套完成特定功能的API，这类项目的文件组织结构通常如下图所示：

 

其中：

contrib

当前项目所依赖的所有第三方软件，可以按类别分设子目录。

doc

项目文档

include

声明外部接口的所有头文件和内联定义文件。

lib

编译好的二进制库文件，可以按编译器、平台分设子目录。

makefile

用于编译项目的makefile文件和project文件等。可以按编译器、平台分设子目录。

src

所有实现文件和声明内部接口的头文件、内联定义文件。可按功能划分；支持编译器、平台等类别分设子目录。

test

存放测试用代码的目录。

应用程序的文件组织形式

与功能模块不同，应用程序是一个交付给最终用于使用的、可以独立运行并提供完整功能的软件产品，它通常不提供编程接口，应用程序的典型文件组织形式如下图所示：

 

contrib

当前项目所依赖的所有第三方软件，可以按类别分设子目录。

doc

项目文档

makefile

用于编译项目的makefile文件和project文件等。可以按编译器、平台分设子目录。

setup

安装程序，以及制作安装程序所需要的项目文件和角本。

src

所有源文件。可按功能划分；支持编译器、平台等类别分设子目录。

test

存放测试用代码的目录。

　

---

命名规则

如果想要有效的管理一个稍微复杂一点的体系，针对其中事物的一套统一、带层次结构、清晰明了的命名准则就是必不可少而且非常好用的工具。

活跃在生物学、化学、军队、监狱、黑社会、恐怖组织等各个领域内的大量有识先辈们都曾经无数次地以实际行动证明了以上公理的正确性。除了上帝（设它可以改变世间万物的秩序）以外，相信没人有实力对它不屑一顾

在软件开发这一高度抽象而且十分复杂的活动中，命名规则的重要性更显得尤为突出。一套定义良好并且完整的、在整个项目中统一使用的命名规范将大大提升源代码的可读性和软件的可维护性。

在引入细节之前，先说明一下命名规范的整体原则：

同一性

在编写一个子模块或派生类的时候，要遵循其基类或整体模块的命名风格，保持命名风格在整个模块中的同一性。

　

标识符组成

标识符采用英文单词或其组合，应当直观且可以拼读，可望文知意，用词应当准确。

　

最小化长度 && 最大化信息量原则

在保持一个标识符意思明确的同时，应当尽量缩短其长度。

　

避免过于相似

不要出现仅靠大小写区分的相似的标识符，例如“i”与“I”，“function”与“Function”等等。

　

避免在不同级别的作用域中重名

程序中不要出现名字完全相同的局部变量和全局变量，尽管两者的作用域不同而不会发生语法错误，但容易使人误解。

　

正确命名具有互斥意义的标识符

用正确的反义词组命名具有互斥意义的标识符，如："nMinValue" 和 "nMaxValue"，"GetName()" 和 "SetName()" ....

　

避免名字中出现数字编号

尽量避免名字中出现数字编号，如Value1,Value2等，除非逻辑上的确需要编号。这是为了防止程序员偷懒，不肯为命名动脑筋而导致产生无意义的名字（因为用数字编号最省事）。

　

类/结构

除了异常类等个别情况（不希望被用户看作一个普通的、正常的类之情况）外，C++类/结构的命名应该遵循以下准则：

　

C++类/结构的命名

类的名称都要以大写字母“C”开头，后跟一个或多个单词。为便于界定，每个单词的首字母要大写。

特别地，由于界面与其它类概念上的巨大差别，规定界面类要以大写字母“I”开头。界面类描述一个服务（一组被命名的操作集合），在C＋＋中，界面与其它类间的最大区别在于，界面类中不包含任何数据结构（属性），也不包括任何具体的操作和实现，界面类通常仅包含一组纯虚函数的声明而不包含任何实现和数据。在一些其它语言中，一个界面也被称作一个接口及其实现契约。

另一个与接口相似的概念是类型，类型与接口的不同点在于，类型可以包含部分接口的实现或包含一些接口默认的或不完整的实现，一个类型也可以包含一些属性。规定类型类要以大写字母“T”开头。例如：轿车类型 "TCar"、线程类型 "TThread" 等等。在C＋＋种，类型类也叫做结点类。

在现实世界中，类型和界面的区别往往比较微妙。在真实代码中，有些类除了包含纯虚函数以外，也可能同时包含几个带简单默认实现的普通虚函数。例如：某个类中可能包含一个（非纯虚）虚方法 IsLoadable，并定义了该方法的默认实现：return false;。我们不难找出很多类似的例子。

以下是一些类型和界面的界定策略：

• 如果一个类中包含静态成员，则一定不是界面
• 如果一个类中包含属性，则一定不是界面
• 如果一个类中包含非虚方法，则一定不是界面
• 如果一个类中包含非公有成员，则一定不是界面
• 如果一个类中包含模板方法，则一定不是界面。
  这里的模板方法是指那些调用了该类中其它虚函数的成员，这样的方法通常用于实现针对某种应用的算法框架，这显然超出了界面的范畴。
  在C＋＋中，模板方法的另一个意思通常指使用函数模板的成员，由于C＋＋函数模板只能是非虚的，所以包含这种方法的类也一定不是界面。
• 通常定义那些不十分明确的接口时，先将其指定为一个界面，必要时再把它提升为一个类型。

模板类的命名规范与实体类相同。

为了更好地表示代码段之间的相关性和增加程序的可读性。我们经常会把一段仅在某个函数内反复使用的代码片段封装为一个函数对象，并定义在这个函数体内。对于这类实现功能简单，并且主要通过 operator() 来使用的类/结构，其名称应当以大写字母“FO”开头，如："FONameChecker" 等。

　

推荐的组成形式

类的命名推荐用"名词"或"形容词＋名词"的形式，例如："CAnalyzer", "CFastVector", "IUnknown", "IDBWriter", "TTimer", "TThread" ....

不同于C++类的概念，传统的C结构体只是一种将一组数据捆绑在一起的方式。传统C结构体的命名规则为：

传统C结构体的命名

传统C结构体的名称全部由大写字母组成，单词间使用下划线界定，例如："SERVICE_STATUS", "DRIVER_INFO" ....

　

函数

函数的命名

函数的名称由一个或多个单词组成。为便于界定，每个单词的首字母要大写。

　

推荐的组成形式

函数名应当使用"动词"或者"动词＋名词"（动宾词组）的形式。例如："GetName()", "SetValue()", "Erase()", "Reserve()" ....

　

保护成员函数

保护成员函数的开头应当加上一个下划线“_”以示区别，例如："_SetState()" ....

　

私有成员函数

类似地，私有成员函数的开头应当加上两个下划线“__”，例如："__DestroyImp()" ....

　

私有成员函数的层次结构表示

通常来说，在一个类中，公有方法、保护方法和私有方法所完成的任务总是呈现一种逐级依次细化的层次结构（意即：保护方法所实现的功能通常比该类中的公有方法更为细小琐碎；类似地，私有方法的功能也比其保护方法更具原子性）。

因此，对于遵循以上规则，并且功能较为复杂的类，在按照“公有、保护、私有”的三级形式划分以后，如果其私有成员中仍然存在明显不同的功能粒度，则可以通过追加更多下划线前缀的形式予以表示。

例如：由三个下划线开头的私有方法“___PushCdr”就要比同一类中，仅由两个下划线开头的私有方法“__MergeConCall”所完成的功能粒度更细小、更琐碎；而四个下划线开头的“____CalcCompensate”则比“___PushCdr”完成的功能 更具原子性。

如果发现类中的功能层数太多（从公有方法到最“原子”的私有方法间，一般不应该超过 7 层），那通常反应一个不良的设计。此时请检查这个类的功能是否过于臃肿，已使接口显得不太清晰。另外一个常见的问题是将无需访问该类中 私有或保护成员的功能定义成了方法。第一个问题可以通过重新划分类层次结构或将一个类分裂为多个类等方法解决。对于第二个问题，由于这些方法无需访问 受限成员，大多数时候都可以把它们转变成局部函数（放在无名空间或使用“static”前缀定义）。

　

成员函数的下划线后缀命名

对一些本应该作为保护或私有成员的函数，由于设计方面的其它考虑（例如：灵活性、功能等方面）将其提升为公有成员的，应该在其后面添加与其原本访问控制级别相应的下划线后缀。

另外，对于其它不推荐直接使用的成员函数（例如：会引起兼容性或可移植性方面问题的函数），也应当在其后面加相应下划线提示。

例如："ioctl_()", "SetSysOpt_()", "GetSysOpt_()", "PreParser__()" ....

　

回调和事件处理函数

回调和事件处理函数习惯以单词“On”开头。例如："_OnTimer()", "OnExit()" ....

　

虚函数

回调函数以外的虚函数习惯以“Do”开头，如："DoRefresh()", "_DoEncryption()" ....

　

　

变量

变量应该是程序中使用最多的标识符了，变量的命名规范可能是一套C++命名准则中最重要的部分：

变量的命名

变量名由作用域前缀＋类型前缀＋一个或多个单词组成。为便于界定，每个单词的首字母要大写。

对于某些用途简单明了的局部变量，也可以使用简化的方式，如：i, j, k, x, y, z ....

　

作用域前缀

作用域前缀标明一个变量的可见范围。作用域可以有如下几种：

前缀

说明

无

局部变量

m_

类的成员变量（member）

sm_

类的静态成员变量（static member）

s_

静态变量（static）

g_

外部全局变量（global）

sg_

静态全局变量（static global）

gg_

进程或动态链接库间共享的全局变量（global global）

除非不得已，否则应该尽可能少使用全局变量。

关于全局变量和局部静态变量的依赖性问题和初始化时的线程安全性问题，请参考：多处理器环境和线程同步的高级话题 一节

　

类型前缀

类型前缀标明一个变量的类型，可以有如下几种：

前缀

说明

n

整型和位域变量（number）

e

枚举型变量（enumeration）

c

字符型变量（char）

b

布尔型变量（bool）

f

浮点型变量（float）

p

指针型变量和迭代子（pointer）

pfn

指向函数的指针变量或指向函数对象的指针（pointer of function）

pm

指向成员的指针（pointer of member）

g

数组（grid）

fo

函数对象（Function Object）

i

类的实例（instance）

对于经常用到的类，也可以定义一些专门的前缀，如：std::string和std::wstring类的前缀可以定义为"st"，std::vector类的前缀可以定义为"v"等等。

类型前缀可以组合使用，例如"gc"表示字符数组，"ppn"表示指向整型的指针的指针等等。

　

数值前缀的特别记法

以“n”作为所有整形前缀是由于大多数情况下，编写程序时不需要过多考虑整形的宽度，但在某些场合中，整形宽度是需要特别注意并且仔细加以区分的，这时可使用如下记法代替“n”前缀：

前缀

说明

b

字节（8bit，byte）

w

字（16bit，word）

dw

双字（32bit，double word）

qw -或- nn

四字（64bit，quad word）

bf

位域（bit field）

对浮点型变量也有类似记法如下：

前缀

说明

f

单精度浮点（32bit，float）

d

双精度浮点（64bit，double）

ld

扩展精度浮点（80bit，long double）

　

推荐的组成形式

变量的名字应当使用"名词"或者"形容词＋名词"。例如："nCode", "m_nState"，"nMaxWidth" ....

　

常量

C++中引入了对常量的支持，常量的命名规则如下：

常量的命名

常量名由类型前缀＋全大写字母组成，单词间通过下划线来界定，如：cDELIMITER, nMAX_BUFFER ....

类型前缀的定义与变量命名规则中的相同。

　

枚举、联合、typedef

枚举、联合及typedef语句都是定义新类型的简单手段，它们的命名规则为：

枚举、联合的命名

由枚举、联合语句定义的类型名由全大写字母组成，单词间通过下划线来界定，如：FAR_PROC, ERROR_TYPE ....

typedef的命名

通常情况下，typedef语句定义的类型名，其命名规范与枚举及联合语句相同，也采用大写字母加下划线的原则。但是在定义一个模板类实例的别名时，为清晰起见，可以考虑酌情使用类的命名原则，例如：

　

typedef CWriter< CSysFile > CSysFileWriter;
typedef std::vector< int > VINT;

　

宏、枚举值

宏、枚举值的命名

宏和枚举值由全大写字母组成，单词间通过下划线来界定，如：ERROR_UNKNOWN, OP_STOP ....

　

名空间

C++名空间是“类”概念的一种退化（大体相当于只包含静态成员且不能实例化的类）。它的引入为标识符名称提供了更好的层次结构，使标识符看起来更加直观简捷，同时大大降低了名字冲突的可能性。

名空间的命名规则包括：

名空间的命名

名空间的名称不应该过长，通常都使用缩写的形式来命名。

例如，一个图形库可以将其所有外部接口存放在名空间"GLIB"中，但是将其换成"GRAPHIC_LIBRARY"就不大合适。

如果碰到较长的名空间，为了简化程序书写，可以使用：

namespace new_name = old_long_name;

语句为其定义一个较短的别名。