Konwencje stylu kodowania

Konwencje stylu kodowania są używane w tej przykładowej serii, aby ułatwić przejrzystość i spójność. Używane są konwencje notacji węgierskiej. Stało się to powszechną praktyką kodowania w programowaniu Win32. Zawierają prefiksową notację zmiennych, które sugerują nazwom zmiennych rodzaj zmiennej.

W poniższej tabeli wymieniono typowe prefiksy.

Przedrostek	Opis
a	Tablica
b	BOOL (int)
c	Char
Cb	Liczba bajtów
Cr	Wzorcowa wartość koloru
cx	Liczba x (krótka)
Dw	DWORD (niepodpisany długi)
f	Flagi (zazwyczaj wiele wartości bitowych)
Fn	Funkcja
g_	Globalny
h	Uchwyt
i	Liczba całkowita
l	Długi
Lp	Wskaźnik długi
m_	Składowa danych klasy
n	Krótki int
p	Wskaźnik
s	Struna
sz	Ciąg zakończony zerem
Tm	Metryka tekstu
u	Niepodpisane int
Ul	Typ bez znaku długi (ULONG)
w	WORD (niepodpisany krótki)
x,y	x, współrzędne y (krótkie)

 

Są one często łączone, jak pokazano poniżej.

Kombinacja prefiksu	Opis
pszMyString	Wskaźnik do ciągu.
m_pszMyString	Wskaźnik do ciągu, który jest składową danych klasy.

 

Inne konwencje są wymienione w poniższej tabeli.

Konwencja	Opis
Klasa CMyClass	Prefiks "C" dla nazw klas języka C++.
COMyObjectClass	Prefiks "CO" dla nazw klas obiektów COM.
CFMyClassFactory	Prefiks "CF" dla nazw fabryk klas COM.
IMyInterface	Prefiks "I" dla nazw klas interfejsu COM.
CImpIMyInterface	Prefiks "CImpI" dla klas implementacji interfejsu COM.

 

Niektóre spójne konwencje bloków nagłówka komentarza są używane w tej przykładowej serii w następujący sposób.

Nagłówek pliku

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

Zwykły blok komentarza

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

Nagłówek deklaracji klasy

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

Nagłówek definicji metody klasy

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

Funkcja nieeksportowana lub lokalna

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

Wyeksportowany nagłówek definicji funkcji

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

Nagłówek deklaracji interfejsu 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*/

Nagłówek deklaracji klasy obiektu 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*/

Wszystkie te konwencje bloków komentarzy mają spójne ciągi znaków rozpoczynających i kończących. Ta spójność wspiera automatyczne przetwarzanie nagłówków w określony sposób. Na przykład skrypty platformy AWK można zapisywać w celu filtrowania nagłówków funkcji w osobnym pliku tekstowym, który może następnie służyć jako podstawa dokumentu specyfikacji. Podobnie, narzędzia takie jak nieobsługiwane narzędzie AUTODUCK (obecnie dostępne w bibliotece Microsoft Developer Network Development Library CD-ROM) mogą służyć do przetwarzania bloków komentarzy w tych nagłówkach.

W poniższej tabeli wymieniono początkowe i końcowe ciągi tokenów używane w przykładowych samouczkach.

Żeton	Opis
/*+	Początek nagłówka pliku
+*/	Koniec nagłówka pliku
/*-	Zwykły blok komentarzy Nagłówek Początek
-*/	Koniec nagłówka bloku komentarza zwykłego
/*C	Początek nagłówka klasy
C*/	Koniec nagłówka klasy
/*M	Początek nagłówka metody
M*/	Koniec nagłówka metody
/*F	Początek nagłówka funkcji
F*/	Koniec nagłówka funkcji
/*Ja	Początek nagłówka interfejsu
Ja*/	Koniec nagłówka interfejsu
/*O	Początek nagłówka klasy obiektu COM
O*/	Koniec nagłówka klasy obiektów COM

 

Te nagłówki mogą być również używane jako sygnały wizualne do szybkiego skanowania plików źródłowych. Zapewniają one również wygodę szybkiego dotarcia do lokalizacji źródłowej, jeśli skonfigurujesz ciągi wyszukiwania w edytorze, a następnie "powtórz ostatnie wyszukiwanie", aby szybko zlokalizować te nagłówki.

Na przykład ciąg wyszukiwania "M+M" zlokalizuje początek nagłówków metody, a "M-M" zlokalizuje początek rzeczywistego kodu definicji/implementacji metody.