Usando os arquivos de origem MFC
A Biblioteca Microsoft Foundation Class (MFC) fornece código-fonte completo. Os arquivos de cabeçalho (.h) estão no diretório \atlmfc\include. Os arquivos de implementação (.cpp) estão no diretório \atlmfc\src\mfc.
Este artigo explica as convenções que o MFC usa para comentar as várias partes de cada classe, o que esses comentários significam e o que você deve esperar encontrar em cada seção. Os assistentes do Visual Studio usam convenções semelhantes para as classes que eles criam para você e você provavelmente achará essas convenções úteis para seu próprio código.
Você pode estar familiarizado com as palavras-chave public, protected e private do C++. Nos arquivos de cabeçalho do MFC, você descobrirá que cada classe pode ter várias delas. Por exemplo, funções e variáveis de membro público podem estar em mais de uma palavra-chave public. Isso ocorre porque o MFC separa funções e variáveis de membro com base em seu uso, não pelo tipo de acesso permitido. O MFC usa private com moderação. Até mesmo os itens considerados detalhes da implementação são frequentemente protected, e muitas vezes são public. Embora o acesso aos detalhes da implementação seja desencorajado, o MFC deixa que você decida.
Nos arquivos de origem do MFC e nos arquivos de cabeçalho que o Assistente de Aplicativo MFC cria, você encontrará comentários como esses dentro de declarações de classe (geralmente nesta ordem):
// Constructors
// Attributes
// Operations
// Overridables
// Implementation
Um exemplo dos comentários
A listagem parcial de classe CStdioFile a seguir usa a maioria dos comentários padrão que o MFC emprega em suas classes para dividir os membros da classe pela maneira como eles são usados:
/*============================================================================*/
// STDIO file implementation
class CStdioFile : public CFile
{
DECLARE_DYNAMIC(CStdioFile)
public:
// Constructors
CStdioFile();
// . . .
// Attributes
FILE* m_pStream; // stdio FILE
// m_hFile from base class is _fileno(m_pStream)
// Operations
// reading and writing strings
virtual void WriteString(LPCTSTR lpsz);
virtual LPTSTR ReadString(_Out_writes_z_(nMax) LPTSTR lpsz, _In_ UINT nMax);
virtual BOOL ReadString(CString& rString);
// Implementation
public:
virtual ~CStdioFile();
#ifdef _DEBUG
void Dump(CDumpContext& dc) const;
#endif
virtual ULONGLONG GetPosition() const;
virtual ULONGLONG GetLength() const;
virtual BOOL Open(LPCTSTR lpszFileName, UINT nOpenFlags, CFileException* pError = NULL);
// . . .
protected:
void CommonBaseInit(FILE* pOpenStream, CAtlTransactionManager* pTM);
void CommonInit(LPCTSTR lpszFileName, UINT nOpenFlags, CAtlTransactionManager* pTM);
};
Esses comentários marcam consistentemente seções da declaração de classe que contêm tipos semelhantes de membros de classe. Tenha em mente que são convenções do MFC, e não regras definidas.
// Comentário sobre construtores
A seção // Constructors de uma declaração de classe MFC declara construtores (no sentido C++) e quaisquer funções de inicialização necessárias para realmente usar o objeto. Por exemplo, CWnd::Create está na seção de construtores porque antes de usar o objeto CWnd, ele deve ser "totalmente construído" chamando primeiro o construtor C++ e, depois, chamando a função Create. Normalmente, esses membros são públicos.
Por exemplo, a classe CStdioFile tem cinco construtores, um dos quais é mostrado na listagem em Um exemplo dos comentários.
// Comentário sobre atributos
A seção // Attributes de uma declaração de classe do MFC contém os atributos públicos (ou propriedades) do objeto. Normalmente, os atributos são variáveis de membro ou funções Get/Set. As funções "Get" e "Set" podem ou não ser virtuais. As funções "Get" geralmente são const porque, na maioria dos casos, elas não têm efeitos colaterais. Esses membros normalmente são públicos. Atributos protegidos e privados normalmente são encontrados na seção de implementação.
Na listagem de exemplo da classe CStdioFile, em Um exemplo dos comentários, a lista inclui uma variável de membro, m_pStream. A classe CDC lista cerca de 20 membros neste comentário.
Observação
Classes grandes, como CDC e CWnd, podem ter tantos membros que simplesmente listar todos os atributos em um grupo não adicionaria muito à clareza. Nesses casos, a biblioteca de classes usa outros comentários como títulos para delinear ainda mais os membros. Por exemplo, CDC usa // Device-Context Functions, // Drawing Tool Functions, // Drawing Attribute Functions e outros. Os grupos que representam atributos seguirão a sintaxe normal descrita acima. Muitas classes OLE têm uma seção de implementação chamada // Interface Maps.
// Comentário sobre operações
A seção // Operations de uma declaração de classe MFC contém funções membro que você pode chamar no objeto para ele faça coisas ou execute ações (execute operações). Essas funções normalmente não são const porque geralmente têm efeitos colaterais. Elas podem ser virtuais ou não, dependendo das necessidades da classe. Normalmente, esses membros são públicos.
Na listagem de exemplo da classe CStdioFile, em Um exemplo dos comentários, a lista inclui três funções membro sob este comentário: WriteString e duas sobrecargas de ReadString.
Assim como acontece com os atributos, as operações podem ser ainda mais subdivididas.
// Comentário sobre substituíveis
A seção // Overridables de uma declaração de classe MFC contém funções virtuais que você pode substituir em uma classe derivada quando precisar modificar o comportamento da classe base. Elas normalmente são nomeadas começando com "On", embora isso não seja estritamente necessário. As funções aqui são projetadas para serem substituídas e geralmente implementam ou fornecem algum tipo de "retorno de chamada" ou "gancho". Normalmente, esses membros são protegidos.
No próprio MFC, as funções virtuais puras são sempre colocadas nesta seção. Uma função virtual pura no C++ assume a forma:
virtual void OnDraw( ) = 0;
Na listagem de exemplo da classe CStdioFile, em Um exemplo dos comentários, a lista não inclui nenhuma seção de substituíveis. A classe CDocument, por outro lado, lista aproximadamente 10 funções membro substituíveis.
Em algumas classes, você também pode ver o comentário // Advanced Overridables. Essas funções são daquelas que somente programadores avançados devem tentar substituir. Você provavelmente nunca precisará substituí-las.
Observação
As convenções descritas neste artigo também funcionam bem, em geral, para métodos e propriedades de Automação (anteriormente conhecida como Automação OLE). Os métodos de automação são semelhantes às operações MFC. As propriedades de automação são semelhantes aos atributos MFC. Os eventos de automação (com suporte para controles ActiveX, anteriormente conhecidos como controles OLE) são semelhantes às funções membro substituíveis do MFC.
// Comentário sobre implementação
A seção // Implementation é a parte mais importante de qualquer declaração de classe MFC.
Esta seção abriga todos os detalhes da implementação. As variáveis de membro e as funções membro podem aparecer nesta seção. Tudo abaixo dessa linha pode mudar em uma versão futura do MFC. A menos que não seja possível, você não deve contar com detalhes abaixo da linha // Implementation. Além disso, os membros declarados abaixo da linha de implementação não estão documentados, embora alguma implementação seja discutida em notas técnicas. As substituições de funções virtuais na classe base residem nesta seção, independentemente da seção em que a função de classe base esteja definida. Quando uma função substitui a implementação da classe base, ela é considerada um detalhe de implementação. Normalmente, esses membros são protegidos, mas nem sempre.
Na listagem CStdioFile em Um exemplo dos comentários, os membros declarados abaixo do comentário // Implementation podem ser declarados como public, protected ou private. Apenas use esses membros com cautela, pois eles podem mudar no futuro. Declarar um grupo de membros como public pode ser necessário para que a implementação da biblioteca de classes funcione corretamente. No entanto, isso não significa que você possa usar com segurança os membros assim declarados.
Observação
Você pode encontrar comentários dos tipos restantes acima ou abaixo do comentário // Implementation. Em ambos os casos, eles descrevem os tipos de membros declarados abaixo deles. Se ocorrerem abaixo do comentário // Implementation, você deverá presumir que os membros podem mudar em versões futuras do MFC.