Include Files

Rule 12.Every include file must contain a mechanism that prevents multiple inclusions of the file. The format of macros used to determine whether the file was included or not must be __FILENAME_H__.

Rule 13.When the following kinds of references are used (in implementation files or in include files), the files declaring them must be included using the#includepreprocessor directive:

• classes that are used as base classes;

• classes that are used as member variables;

• classes that appear as return types or as argument types in function/member function prototypes.

• function prototypes for functions/member functions used in inline member functions defined in the file.

Exception:If those declarations are included in a precompiled header file, such as STDAFX.H, they may be not included in other include files. Implementation files must include the precompiled header file, instead.

Rule 14.Definitions of classes that are only accessed via pointers (*) or references (&) must not be included as include files.

Rule 15.(MFC specific) Every implementation file must define a static constant stringTHIS_FILEthat identifies the file name.

Rule 16.Never specify relative paths in#includedirectives.

Exception:#includedirectives for standard C run-time library include files (for example,#include <sys\stat.h>) may use relative paths.

Rec. 6.Use the directive#include"filename.h"for user-prepared include files.

Rec. 7.Use the directive#include <filename.h>for include files from libraries.

Rec. 8.Use the#pragma comment(lib, "library.lib")preprocessor directive for used library files.

Rec. 9.Never include other files in an .INL file.

Rec. 10.Use preliminary definitions for all classes declared in an include file.

The easiest way to avoid multiple includes of files is by using an #ifndef/#defineblock in the beginning of the file and an#endifat the end of the file. The same problem can be solved by using a#pragma oncepreprocessor directive. All wizard generated macros, for example, those including the UUID sequences in their bodies should be rewritten according to the format thatRule 12states. SeeExample 6.

The number of included files should be minimized. If a file is included in an include file, then every implementation file that includes the second include file must be re-compiled whenever the first file is modified. A simple modification in one include file can make it necessary to re-compile a large number of files.

When only referring to pointers or references to types defined in a file, it is often not necessary to include that file. It may suffice to use a forward declaration to inform the compiler the class exists. Another alternative is to precede each declaration of a pointer to the class with the keyword class.

If a file contains information only needed in an implementation file, that file should not be included in another include file. Otherwise, when the information is no longer needed in the implementation file, it may be necessary to re-compile each file that uses the interface defined in the include file. See Examples 7and8.

THIS_FILEstrings are used by MFCASSERTandVERIFYmacros and by the MFC mechanism detecting memory leaks. SeeExample 9.

A relative path in the #includedirective can make you correct a lot of code when it becomes necessary to change the file location. For this reason, relative search paths muar be avoided when including files. Instead, search paths should be provided in the project.

Every C++ course teaches the difference between the include directives for user-prepared and for library include files. If the file name is bracketed between <and>, the preprocessor will not search for the file in the default directory. This reduces the risk of unintended name collisions between user-prepared and library include files.

It is usually helpful to know all the libraries an include or implementation file uses. It helps to avoid explicit library declarations in the project.