Convenciones de estilo de codificación

Artículo
06/13/2023

Las convenciones de estilo de codificación se usan en esta serie de ejemplo para ayudar a la claridad y la coherencia. Se usan las convenciones de notación "húngaro". Estos se han convertido en una práctica de codificación común en la programación win32. Incluyen notaciones de prefijo de variable que proporcionan a los nombres de variable una sugerencia del tipo de la variable.

En la tabla siguiente se enumeran los prefijos comunes.

Prefijo	Descripción
a	Array
b	BOOL (int)
c	Char
cb	Recuento de bytes
cr	Valor de referencia de color
Cx	Recuento de x (short)
dw	DWORD (unsigned long)
f	Marcas (normalmente varios valores de bits)
fn	Función
G_	Global
h	Handle
i	Entero
l	long
lp	Puntero largo
M_	Miembro de datos de una clase
n	Short int
p	Puntero
s	String
sz	Cadena terminada en cero
tm	Métrica de texto
u	Unsigned int
Ul	Long sin signo (ULONG)
w	WORD (unsigned short)
x,y	coordenadas x, y (short)

A menudo se combinan, como se muestra a continuación.

Combinación de prefijo	Descripción
pszMyString	Puntero a una cadena.
m_pszMyString	Puntero a una cadena que es un miembro de datos de una clase.

En la tabla siguiente se enumeran otras convenciones.

Convención	Descripción
CMyClass	Prefijo "C" para los nombres de clase de C++.
COMyObjectClass	Prefijo "CO" para los nombres de clase de objeto COM.
CFMyClassFactory	Prefijo "CF" para nombres de generador de clases COM.
IMyInterface	Prefijo "I" para los nombres de clase de interfaz COM.
CImpIMyInterface	Prefijo "CImpI" para las clases de implementación de interfaz COM.

Algunas convenciones coherentes para los bloques de encabezado de comentario se usan en esta serie de ejemplo como se indica a continuación.

Encabezado de archivo

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

Bloque de comentarios sin formato

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

Encabezado de declaración de clase

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

Encabezado de definición del método de clase

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

Función local o noportada

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

Encabezado de definición de función exportada

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

Encabezado de declaración de interfaz 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*/

Encabezado de declaración de clase de objeto 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*/

Todas estas convenciones de bloque de comentarios tienen cadenas de token inicial y final coherentes. Esta coherencia admite el procesamiento automático de los encabezados de alguna manera. Por ejemplo, los scripts de AWK se pueden escribir para filtrar los encabezados de función en un archivo de texto independiente que, a continuación, puede servir como base para un documento de especificación. De forma similar, se pueden usar herramientas como la utilidad AUTODUCK no compatible (disponible actualmente en la CD-ROM de la biblioteca de desarrollo de red para desarrolladores de Microsoft) para procesar los bloques de comentarios en estos encabezados.

En la tabla siguiente se enumeran las cadenas de token iniciales y finales que se usan en los tutoriales de ejemplo.

Token	Descripción
/*+	Inicio del encabezado de archivo
+*/	Fin del encabezado de archivo
/*-	Inicio del encabezado del bloque de comentarios sin formato
-*/	Fin del encabezado del bloque de comentarios sin formato
/*C	Comienzo del encabezado de clase
C*/	Fin del encabezado de clase
/*M	Comienzo del encabezado del método
M*/	Fin del encabezado del método
/*F	Comienzo del encabezado de función
F*/	Fin del encabezado de función
/*I	Inicio del encabezado de interfaz
I*/	Fin del encabezado de interfaz
/*O	Comienzo del encabezado de clase de objeto COM
O*/	Fin de encabezado de clase de objeto COM

Estos encabezados también se pueden usar como indicaciones visuales para el examen rápido de archivos de origen. También proporcionan comodidad para llegar rápidamente a alguna ubicación de origen si configura cadenas de búsqueda en el editor y luego "repetir la última búsqueda" para localizar rápidamente estos encabezados.

Por ejemplo, la cadena de búsqueda "M+M" buscará el inicio de los encabezados de método y "M-M" buscará el principio del código de definición o implementación del método real.

Compartir a través de