Convenzioni di stile di codifica

Le convenzioni di stile di codifica vengono usate in questa serie di esempi per facilitare la chiarezza e la coerenza. Vengono usate le convenzioni di notazione "ungherese". Questi sono diventati una pratica comune di codifica nella programmazione Win32. Includono le notazioni del prefisso delle variabili che danno ai nomi delle variabili un suggerimento del tipo della variabile.

La tabella seguente elenca i prefissi comuni.

Prefisso	Descrizione
a	Array
b	BOOL (int)
c	Char
Cb	Numero di byte
Cr	Valore di riferimento colore
Cx	Numero di x (breve)
dw	DWORD (long senza segno)
f	Flag (in genere più valori di bit)
fn	Funzione
G_	Globale
h	Handle
i	Integer
l	long
lp	Puntatore lungo
M_	Membro dati di una classe
n	Breve int
p	Puntatore
s	string
sz	Stringa terminata zero
tm	Metrica di testo
u	Senza segno int
Ul	Unsigned long (ULONG)
w	WORD (unsigned short)
x,y	coordinate x, y (breve)

 

Queste sono spesso combinate, come illustrato di seguito.

Combinazione di prefisso	Descrizione
pszMyString	Puntatore a una stringa.
m_pszMyString	Puntatore a una stringa membro dati di una classe.

 

Altre convenzioni sono elencate nella tabella seguente.

Convenzione	Descrizione
CMyClass	Prefisso 'C' per i nomi di classe C++.
COMyObjectClass	Prefisso 'CO' per i nomi delle classi di oggetti COM.
CFMyClassFactory	Prefisso 'CF' per i nomi della classe COM.
IMyInterface	Prefisso 'I' per i nomi delle classi di interfaccia COM.
CImpIMyInterface	Prefisso 'CImpI' per le classi di implementazione dell'interfaccia COM.

 

Alcune convenzioni coerenti per i blocchi di intestazione di commento vengono usate in questa serie di esempi come indicato di seguito.

Intestazione file

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

Blocco commento normale

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

Intestazione dichiarazione di classe

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

Intestazione definizione del metodo di classe

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

Funzione non esportata o locale

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

Intestazione di definizione della funzione esportata

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

Intestazione della dichiarazione dell'interfaccia 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*/

Intestazione della dichiarazione della classe oggetto 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*/

Tutte queste convenzioni dei blocchi di commento hanno stringhe di token iniziali e finali coerenti. Questa coerenza supporta l'elaborazione automatica delle intestazioni in qualche modo. Ad esempio, gli script AWK possono essere scritti per filtrare le intestazioni della funzione in un file di testo separato che può quindi fungere da base per un documento di specifica. Analogamente, gli strumenti come l'utilità AUTODUCK non supportata (attualmente disponibile nel CD-ROM della libreria di sviluppo di Microsoft Developer Network) possono essere usati per elaborare i blocchi di commento in queste intestazioni.

La tabella seguente elenca le stringhe di token iniziali e finali usate nelle esercitazioni di esempio.

token	Descrizione
/*+	Inizio intestazione file
+*/	Fine intestazione file
/*-	Intestazione del blocco di commento normale Begin
-*/	Fine intestazione blocco commento normale
/*C	Intestazione classe Begin
C*/	Fine intestazione classe
/*M	Inizio intestazione metodo
M*/	Fine intestazione metodo
/*F	Inizio intestazione funzione
F*/	Fine intestazione funzione
/*Ho	Inizio intestazione interfaccia
Ho*/	Fine intestazione interfaccia
/*O	Inizio intestazione classe oggetto COM
O*/	Fine intestazione classe oggetto COM

 

Queste intestazioni possono essere usate anche come segnali visivi per l'analisi rapida dei file di origine. Offrono anche praticità per accedere rapidamente a un percorso di origine se si configurano stringhe di ricerca nell'editor e quindi si ripete l'ultima ricerca per individuare rapidamente queste intestazioni.

Ad esempio, la stringa di ricerca "M+M" individua l'inizio delle intestazioni del metodo e "M-M" individua l'inizio del codice di definizione/implementazione del metodo effettivo.