编码样式约定

  • 项目

此示例系列中使用了编码样式约定来帮助实现清晰和一致性。 使用“匈牙利”表示法约定。 这些已成为 Win32 编程中的常见编码做法。 它们包括变量前缀表示法，这些表示法为变量名称提供变量类型的建议。

下表列出了常见前缀。

前缀 说明
a 数组
b BOOL (int)
c Char
cb 字节计数
cr 颜色参考值
cx x (短) 计数
dw DWORD (无符号长)
f 标志通常 (多个位值)
fn 函数
G_ 全球
h Handle
i 整数
l Long
lp 长指针
m_ 类的数据成员
n Short int
p 指针
s 字符串
sz 以零结尾的字符串
tm 文本指标
u 未签名的 int
Ul 无符号长 (ULONG)
w WORD (无符号短)
x，y x、y 坐标 (短)

 

它们通常组合在一起，如下所示。

前缀组合 说明
pszMyString 指向字符串的指针。
m_pszMyString 指向作为类的数据成员的字符串的指针。

 

下表列出了其他约定。

约定 说明
CMyClass C++ 类名的前缀“C”。
COMyObjectClass COM 对象类名的前缀“CO”。
CFMyClassFactory COM 类工厂名称的前缀“CF”。
IMyInterface COM 接口类名的前缀“I”。
CImpIMyInterface COM 接口实现类的前缀“CImpI”。

 

此示例系列中使用了注释标头块的一些一致约定，如下所示。

文件头

/*+===================================================================
  File:      MYFILE.EXT

  Summary:   Brief summary of the file contents and purpose.

  Classes:   Classes declared or used (in source files).

  Functions: Functions exported (in source files).

  Origin:    Indications of where content may have come from. This
             is not a change history but rather a reference to the
             editor-inheritance behind the content or other
             indications about the origin of the source.

  Copyright and Legal notices.
  Copyright and Legal notices.
===================================================================+*/

纯注释块

/*--------------------------------------------------------------------
  Plain block of comment text that usually takes several lines.
  Plain block of comment text that usually takes several lines.
--------------------------------------------------------------------*/

类声明标头

/*C+C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C
  Class:    CMyClass

  Summary:  Short summary of purpose and content of CMyClass.
            Short summary of purpose and content of CMyClass.

  Methods:  MyMethodOne
              Short description of MyMethodOne.
            MyMethodTwo
              Short description of MyMethodTwo.
            CMyClass
              Constructor.
            ~CMyClass
              Destructor.
C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C-C*/

类方法定义标头

/*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  Method:   CMyClass::MyMethodOne

  Summary:  Short summary of purpose and content of MyMethodOne.
            Short summary of purpose and content of MyMethodOne.

  Args:     MYTYPE MyArgOne
              Short description of argument MyArgOne.
            MYTYPE MyArgTwo
              Short description of argument MyArgTwo.

  Modifies: [list of member data variables modified by this method].

  Returns:  MYRETURNTYPE
              Short description of meaning of the return type values.
M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/

未导出或本地函数

/*F+F+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  Function: MyLocalFunction

  Summary:  What MyLocalFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
-----------------------------------------------------------------F-F*/

导出的函数定义标头

/*F+F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F
  Function: MyFunction

  Summary:  What MyFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F-F*/

COM 接口声明标头

/*I+I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I
  Interface: IMyInterface

  Summary:   Short summary of what features the interface can bring to
             a COM Component.

  Methods:   MYTYPE MyMethodOne
               Description.
             MYTYPE MyMethodTwo
               Description.
I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I-I*/

COM 对象类声明标头

/*O+O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O
  ObjectClass: COMyCOMObject

  Summary:     Short summary of purpose and content of this object.

  Interfaces:  IUnknown
                 Standard interface providing COM object features.
               IMyInterfaceOne
                 Description.
               IMyInterfaceTwo
                 Description.

  Aggregation: [whether this COM Object is aggregatable or not]
O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O-O*/

所有这些注释块约定都具有一致的开始和结束标记字符串。 这种一致性支持以某种方式自动处理标头。 例如，可以编写 AWK 脚本，将函数标头筛选到单独的文本文件中，然后该文件可用作规范文档的基础。 同样，Microsoft 开发人员网络开发库 CD-ROM) 上当前提供的不受支持的 AUTODUCK 实用工具 (可用于处理这些标头中的注释块。

下表列出了示例教程中使用的开始和结束标记字符串。

令牌 说明
/*+ 文件头开始
+*/ 文件头端
/*- 普通注释块标头开始
-*/ 纯注释块标头结尾
/*C 类标头开始
C*/ 类标头结尾
/*M 方法标头开始
M*/ 方法标头结尾
/*F 函数标头 Begin
F*/ 函数标头结尾
/*我 接口标头开始
我*/ 接口标头端
/*O COM 对象类标头开始
O*/ COM 对象类标头结尾

 

这些标头还可用作快速扫描源文件的视觉提示。 如果在编辑器中设置搜索字符串，然后“重复最后一次搜索”以快速找到这些标头，则它们还为快速访问某些源位置提供了便利。

例如，搜索字符串“M+M”将查找方法标头的开头，“M-M”将查找实际方法定义/实现代码的开头。