編碼樣式慣例

發行項
06/13/2023

此範例系列會使用編碼樣式慣例來協助清楚明瞭和一致性。使用「匈牙利文」標記法慣例。這些是 Win32 程式設計中的常見程式碼撰寫做法。它們包含變數前置詞標記法，可為變數名稱提供變數類型的建議。

下表列出常見的前置詞。

前置詞	描述
a	Array
b	BOOL (int)
c	Char
cb	位元組計數
cr	色彩參考值
殘雪	x (簡短) 計數
dw	DWORD (未簽署的長)
f	旗標 (通常是多個位值)
fn	函式
G_	全球
h	Handle
i	整數
l	long
lp	長指標
m_	類別的資料成員
n	簡短 int
p	Pointer
s	String
sz	零終止字串
tm	文字計量
u	未簽署的 int
Ul	不帶正負號的長 (ULONG)
w	WORD (不帶正負號的簡短)
x，y	x、y 座標 (短)

這些通常會結合在一起，如下所示。

前置片語合	Description
pszMyString	字串的指標。
m_pszMyString	字串的指標，該字串是類別的資料成員。

下表列出其他慣例。

慣例	Description
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 公用 (程式之類的工具，可用來處理這些標頭中的批註區塊。

下表列出範例教學課程中使用的開頭和結束標記字串。

Token	描述
/*+	檔頭開始
+*/	檔頭結尾
/*-	純批註區塊標頭開始
-*/	純批註區塊標頭結尾
/*C	類別標頭開始
C*/	類別標頭結尾
/*M	方法標頭開始
M*/	方法標頭結尾
/*F	函式標頭開始
F*/	函式標頭結尾
/*我	介面標頭開始
我*/	介面標頭結尾
/*O	COM 物件類別標頭開始
O*/	COM 物件類別標頭結尾

這些標頭也可用來作為視覺提示，以快速掃描來源檔案。如果您在編輯器中設定搜尋字串，然後「重複最後搜尋」，快速找出這些標頭，它們也會提供快速進入某些來源位置的便利性。

例如，搜尋字串「M+M」會找出方法標頭的開頭，而「M-M」會找出實際方法定義/實作程式碼的開頭。

共用方式為