Using the MFC source files

The Microsoft Foundation Class (MFC) Library supplies full source code. Header files (.h) are in the \atlmfc\include directory. Implementation files (.cpp) are in the \atlmfc\src\mfc directory.

This article explains the conventions that MFC uses to comment the various parts of each class, what these comments mean, and what you should expect to find in each section. The Visual Studio wizards use similar conventions for the classes that they create for you, and you'll probably find these conventions useful for your own code.

You might be familiar with the public, protected, and private C++ keywords. In the MFC header files, you'll find each class may have several of each of them. For example, public member variables and functions might be under more than one public keyword. It's because MFC separates member variables and functions based on their use, not by the type of access allowed. MFC uses private sparingly. Even items considered implementation details are often protected, and many times are public. Although access to the implementation details is discouraged, MFC leaves the decision to you.

In both the MFC source files and the header files that the MFC Application Wizard creates, you'll find comments like these ones within class declarations (usually in this order):

// Constructors

// Attributes

// Operations

// Overridables

// Implementation

An example of the comments

The following partial listing of class CStdioFile uses most of the standard comments that MFC employs in its classes to divide class members by the ways they're used:

/*============================================================================*/
// 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);
};

These comments consistently mark sections of the class declaration that contain similar kinds of class members. Keep in mind that they're MFC conventions, not set rules.

// Constructors comment

The // Constructors section of an MFC class declaration declares constructors (in the C++ sense) and any initialization functions required to really use the object. For example, CWnd::Create is in the constructors section because before you use the CWnd object, it must be "fully constructed" by first calling the C++ constructor and then calling the Create function. Typically, these members are public.

For example, class CStdioFile has five constructors, one of which is shown in the listing under An example of the comments.

// Attributes comment

The // Attributes section of an MFC class declaration contains the public attributes (or properties) of the object. Typically the attributes are member variables, or Get/Set functions. The "Get" and "Set" functions may or may not be virtual. The "Get" functions are often const, because in most cases they don't have side effects. These members are normally public. Protected and private attributes are typically found in the implementation section.

In the sample listing from class CStdioFile, under An example of the comments, the list includes one member variable, m_pStream. Class CDC lists nearly 20 members under this comment.

// Operations comment

The // Operations section of an MFC class declaration contains member functions that you can call on the object to make it do things or take actions (perform operations). These functions are typically non-const because they usually have side effects. They may be virtual or nonvirtual depending on the needs of the class. Typically, these members are public.

In the sample listing from class CStdioFile, in An example of the comments, the list includes three member functions under this comment: WriteString and two overloads of ReadString.

As with attributes, operations can be further subdivided.

// Overridables comment

The // Overridables section of an MFC class declaration contains virtual functions that you can override in a derived class when you need to modify the base class behavior. They're typically named starting with "On", although it's not strictly necessary. Functions here are designed to be overridden, and often implement or provide some sort of "callback" or "hook." Typically, these members are protected.

In MFC itself, pure virtual functions are always placed in this section. A pure virtual function in C++ takes the form:

virtual void OnDraw( ) = 0;

In the sample listing from class CStdioFile, in An example of the comments, the list includes no overridables section. Class CDocument, on the other hand, lists approximately 10 overridable member functions.

In some classes, you may also see the comment // Advanced Overridables. These functions are ones that only advanced programmers should attempt to override. You'll probably never need to override them.

// Implementation comment

The // Implementation section is the most important part of any MFC class declaration.

This section houses all implementation details. Both member variables and member functions can appear in this section. Everything below this line could change in a future release of MFC. Unless you can't avoid it, you shouldn't rely on details below the // Implementation line. In addition, members declared below the implementation line are undocumented, although some implementation is discussed in technical notes. Overrides of virtual functions in the base class reside in this section, regardless of which section the base class function is defined in. When a function overrides the base class implementation, it's considered an implementation detail. Typically, these members are protected, but not always.

In the CStdioFile listing under An example of the comments, members declared below the // Implementation comment may be declared as public, protected, or private. Only use these members with caution, because they may change in the future. Declaring a group of members as public may be necessary for the class library implementation to work correctly. However, it doesn't mean that you may safely use the members so declared.

See also

General MFC Topics