Convenções de estilo de codificação

Artigo
06/12/2023

As convenções de estilo de codificação são usadas nesta série de exemplo para ajudar na clareza e consistência. As convenções de notação "húngara" são usadas. Elas se tornaram uma prática comum de codificação na programação do Win32. Elas incluem notações de prefixo variável que dão a nomes de variáveis uma sugestão do tipo da variável.

A tabela a seguir lista prefixos comuns.

Prefixo	Descrição
um	Array
b	BOOL (int)
c	Char
cb	Contagem de bytes
cr	Valor de referência de cor
Cx	Contagem de x (curto)
dw	DWORD (long sem sinal)
f	Sinalizadores (geralmente valores de vários bits)
fn	Função
G_	Global
h	Handle
i	Inteiro
l	long
lp	Ponteiro longo
M_	Membro de dados de uma classe
n	Int curto
p	Ponteiro
s	String
Sz	Cadeia de caracteres terminada zero
tm	Métrica de texto
u	Int sem sinal
Ul	Long sem sinal (ULONG)
w	WORD (sem sinal curto)
x,y	Coordenadas x, y (curto)

Geralmente, eles são combinados, como no exemplo a seguir.

Combinação de prefixo	Descrição
pszMyString	Um ponteiro para uma cadeia de caracteres.
m_pszMyString	Um ponteiro para uma cadeia de caracteres que é um membro de dados de uma classe.

Outras convenções são listadas na tabela a seguir.

Convenção	Descrição
Cmyclass	Prefixo 'C' para nomes de classe C++.
COMyObjectClass	Prefixo 'CO' para nomes de classe de objeto COM.
CFMyClassFactory	Prefixo 'CF' para nomes de fábrica de classes COM.
Imyinterface	Prefixo 'I' para nomes de classe de interface COM.
CImpIMyInterface	Prefixo 'CImpI' para classes de implementação de interface COM.

Algumas convenções consistentes para blocos de cabeçalho de comentário são usadas nesta série de exemplo da seguinte maneira.

Cabeçalho do Arquivo

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

Bloco de Comentários Sem Formatação

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

Cabeçalho de declaração 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*/

Cabeçalho de definição do método 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*/

Função local ou sem suporte

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

Cabeçalho de definição de função 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*/

Cabeçalho de declaração da 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*/

Cabeçalho de declaração da classe 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 essas convenções de bloco de comentário têm cadeias de caracteres de token de início e término consistentes. Essa consistência dá suporte ao processamento automático dos cabeçalhos de alguma forma. Por exemplo, scripts AWK podem ser gravados para filtrar os cabeçalhos de função em um arquivo de texto separado que pode servir como base para um documento de especificação. Da mesma forma, ferramentas como o utilitário AUTODUCK sem suporte (atualmente disponível no CD-ROM da Biblioteca de Desenvolvimento de Rede do Desenvolvedor da Microsoft) podem ser usadas para processar os blocos de comentários nesses cabeçalhos.

A tabela a seguir lista as cadeias de caracteres de token inicial e final usadas em tutoriais de exemplo.

Token	Descrição
/*+	Início do Cabeçalho do Arquivo
+*/	Fim do cabeçalho do arquivo
/*-	Início do cabeçalho do bloco de comentários sem formatação
-*/	Fim do cabeçalho do bloco de comentário sem formatação
/*C	Início do cabeçalho de classe
C*/	Fim do Cabeçalho de Classe
/*M	Início do Cabeçalho do Método
M*/	Final do cabeçalho do método
/*F	Início do Cabeçalho da Função
F*/	Final do cabeçalho da função
/*Eu	Início do cabeçalho da interface
Eu*/	Fim do cabeçalho da interface
/*O	Cabeçalho da classe de objeto COM Begin
O*/	Final do cabeçalho da classe de objeto COM

Esses cabeçalhos também podem ser usados como indicações visuais para verificação rápida de arquivos de origem. Eles também fornecem conveniência para acessar rapidamente algum local de origem se você configurar cadeias de caracteres de pesquisa em seu editor e, em seguida, "repetir a última pesquisa" para localizar rapidamente esses cabeçalhos.

Por exemplo, a cadeia de caracteres de pesquisa "M+M" localizará o início dos cabeçalhos do método e "M-M" localizará o início do código de definição/implementação do método real.

Compartilhar via