Konventionen für Codierungsstile

Codierungsstilkonventionen werden in dieser Beispielreihe verwendet, um Klarheit und Konsistenz zu gewährleisten. Es werden die "ungarischen" Notationskonventionen verwendet. Diese sind zu einer gängigen Programmierpraxis in der Win32-Programmierung geworden. Sie enthalten Variablenpräfixnotationen, die Variablennamen einen Vorschlag für den Typ der Variablen geben.

In der folgenden Tabelle sind allgemeine Präfixe aufgeführt.

Präfix	BESCHREIBUNG
a	Array
b	BOOL (int)
c	Char
cb	Anzahl der Bytes
cr	Farbverweiswert
Cx	Anzahl von x (kurz)
dw	DWORD (unsigned long)
f	Flags (in der Regel mehrere Bitwerte)
fn	Funktion
G_	Global
h	Handle
i	Integer
l	Long
lp	Langer Zeiger
M_	Datenmember einer Klasse
n	Kurz int
p	Zeiger
s	String
sz	Null beendete Zeichenfolge
tm	Textmetrik
u	Unsigned int
Ul	Unsigned long (ULONG)
w	WORD (unsigned short)
x,y	x- und y-Koordinaten (kurz)

 

Diese werden häufig kombiniert, wie im Folgenden gezeigt.

Präfixkombination	BESCHREIBUNG
pszMyString	Ein Zeiger auf eine Zeichenfolge.
m_pszMyString	Ein Zeiger auf eine Zeichenfolge, die ein Datenmember einer Klasse ist.

 

Weitere Konventionen sind in der folgenden Tabelle aufgeführt.

Konvention	BESCHREIBUNG
CMyClass	Präfix "C" für C++-Klassennamen.
COMyObjectClass	Präfix "CO" für COM-Objektklassennamen.
CFMyClassFactory	Präfix "CF" für COM-Klassenfactorynamen.
IMyInterface	Präfix "I" für COM-Schnittstellenklassennamen.
CImpIMyInterface	Präfix "CImpI" für COM-Schnittstellenimplementierungsklassen.

 

Einige konsistente Konventionen für Kommentarheaderblöcke werden in dieser Beispielreihe wie folgt verwendet.

Dateiheader

/*+===================================================================
  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.
===================================================================+*/

Nur Kommentarblock

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

Klassendeklarationsheader

/*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*/

Klassenmethodendefinitionsheader

/*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*/

Nicht exportierte oder lokale Funktion

/*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*/

Exportierter Funktionsdefinitionsheader

/*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-Schnittstellendeklarationsheader

/*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-Objektklassendeklarationsheader

/*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*/

Alle diese Kommentarblockkonventionen verfügen über konsistente Anfangs- und Endtokenzeichenfolgen. Diese Konsistenz unterstützt die automatische Verarbeitung der Header in gewisser Weise. Beispielsweise können AWK-Skripts geschrieben werden, um die Funktionsheader in eine separate Textdatei zu filtern, die dann als Grundlage für ein Spezifikationsdokument dienen kann. Ebenso können Tools wie das nicht unterstützte Hilfsprogramm AUTODUCK (derzeit auf der CD-ROM der Microsoft Developer Network Development Library verfügbar) verwendet werden, um die Kommentarblöcke in diesen Headern zu verarbeiten.

In der folgenden Tabelle sind die in Beispieltutorials verwendeten Anfangs- und Endtokenzeichenfolgen aufgeführt.

Token	BESCHREIBUNG
/*+	Dateiheader begin
+*/	Dateiheaderende
/*-	Nur-Kommentarblock Header Begin
-*/	Kopfzeilenende des einfachen Kommentarblocks
/*C	Klassenheader begin
C*/	Klassenheaderende
/*M	Methodenheader begin
M*/	Methodenheaderende
/*F	Funktionsheader begin
F*/	Funktionsheaderende
/*Ich	Interface Header Begin
Ich*/	Schnittstellenheaderende
/*O	COM Object Class Header Begin
O*/	Headerende der COM-Objektklasse

 

Diese Header können auch als visuelle Hinweise für die schnelle Überprüfung von Quelldateien verwendet werden. Sie bieten auch Komfort für den schnellen Zugriff auf einen Quellspeicherort, wenn Sie Suchzeichenfolgen in Ihrem Editor einrichten und dann die letzte Suche wiederholen, um diese Header schnell zu finden.

Beispielsweise findet die Suchzeichenfolge "M+M" den Anfang der Methodenheader und "M-M" den Anfang des tatsächlichen Methodendefinitions-/Implementierungscodes.