Conventions de style de codage

Les conventions de style de codage sont utilisées dans cet exemple de série pour faciliter la clarté et la cohérence. Les conventions de notation « hongroise » sont utilisées. Celles-ci sont devenues une pratique de codage courante dans la programmation Win32. Ils incluent des notations de préfixe de variable qui donnent aux noms de variables une suggestion du type de la variable.

Le tableau suivant répertorie les préfixes courants.

Préfixe	Description
a	Array
b	BOOL (int)
c	Char
cb	Nombre d’octets
cr	Valeur de référence de couleur
Cx	Nombre de x (court)
dw	DWORD (long non signé)
f	Indicateurs (généralement plusieurs valeurs de bits)
fn	Fonction
G_	Global
h	Handle
i	Integer
l	Long
lp	Pointeur long
M_	Membre de données d’une classe
n	Short int
p	Pointeur
s	String
sz	Chaîne sans fin
tm	Métrique de texte
u	Int non signé
Ul	Long non signé (ULONG)
w	WORD (court non signé)
x,y	coordonnées x, y (courte)

 

Ces éléments sont souvent combinés, comme dans ce qui suit.

Combinaison de préfixes	Description
pszMyString	Pointeur vers une chaîne.
m_pszMyString	Pointeur vers une chaîne qui est un membre de données d’une classe.

 

D’autres conventions sont répertoriées dans le tableau suivant.

Convention	Description
CMyClass	Préfixe « C » pour les noms de classes C++.
COMyObjectClass	Préfixe « CO » pour les noms de classes d’objets COM.
CFMyClassFactory	Préfixe 'CF' pour les noms de fabrique de classes COM.
IMyInterface	Préfixe « I » pour les noms de classes d’interface COM.
CImpIMyInterface	Préfixe « CImpI » pour les classes d’implémentation d’interface COM.

 

Certaines conventions cohérentes pour les blocs d’en-tête de commentaire sont utilisées dans cet exemple de série, comme suit.

En-tête de fichier

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

Bloc de commentaires bruts

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

En-tête de déclaration de 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*/

En-tête de définition de méthode de 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*/

Fonction locale ou non exporté

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

En-tête de définition de fonction exporté

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

En-tête de déclaration d’interface 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*/

En-tête de déclaration de classe d’objet 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*/

Toutes ces conventions de blocs de commentaires ont des chaînes de jeton de début et de fin cohérentes. Cette cohérence prend en charge le traitement automatique des en-têtes d’une manière ou d’une autre. Par exemple, les scripts AWK peuvent être écrits pour filtrer les en-têtes de fonction dans un fichier texte distinct qui peut ensuite servir de base à un document de spécification. De même, des outils comme l’utilitaire AUTODUCK non pris en charge (actuellement disponible sur le CD-ROM de la bibliothèque de développement Microsoft Developer Network) peuvent être utilisés pour traiter les blocs de commentaires dans ces en-têtes.

Le tableau suivant répertorie les chaînes de jetons de début et de fin utilisées dans des exemples de didacticiels.

par jeton	Description
/*+	Début de l’en-tête de fichier
+*/	Fin de l’en-tête de fichier
/*-	Début de l’en-tête du bloc de commentaires brut
-*/	Fin d’en-tête du bloc de commentaires brut
/*C	Début de l’en-tête de classe
C*/	Fin d’en-tête de classe
/*M	Début de l’en-tête de la méthode
M*/	Fin d’en-tête de méthode
/*F	Début de l’en-tête de fonction
F*/	Fin de l’en-tête de fonction
/*Je	Début de l’en-tête d’interface
Je*/	Fin d’en-tête d’interface
/*O	Début de l’en-tête de classe d’objet COM
O*/	Fin d’en-tête de classe d’objet COM

 

Ces en-têtes peuvent également être utilisés comme signaux visuels pour une analyse rapide des fichiers sources. Ils permettent également d’accéder rapidement à un emplacement source si vous configurez des chaînes de recherche dans votre éditeur, puis « répétez la dernière recherche » pour localiser rapidement ces en-têtes.

Par exemple, la chaîne de recherche « M+M » localisera le début des en-têtes de méthode, et « M-M » localisera le début de la définition/du code d’implémentation de la méthode réelle.