Section C.1. The Preprocessor: For #including Files

This appendix explains some of the mysteries of the C preprocessor, class declarations versus including headers, and some best practices to reduce dependencies between header files.

In C++, code reuse is indicated by the presence of a preprocessor directive, #include, in source code and header files. We #include header files that contain things like class or namespace definitions, const definitions, function prototypes, and so forth. These files are literally included in our own files before the compiler begins to translate our code.

The compiler will report an error if it sees any identifier defined more than once. It will tolerate repeated declarations but not repeated definitions.^[1] To prevent repeated definitions, we are always careful to use an #ifndef wrapper around each header file. This tells the C preprocessor to skip the contents if it has already seen them. Lets examine the following class definition in Example C.1.

^[1] We discuss the difference between declaration and definition in Section 20.1.

Example C.1. src/preprocessor/constraintmap.h

#ifndef CONSTRAINTMAP_H
#define CONSTRAINTMAP_H

/* included class definitions: */
#include 
#include 

class Constraint; <-- 1

class ConstraintMap : public QHash { <-- 2

private:
 Constraint* m_Constraintptr; <-- 3
// Constraint m_ConstraintObj; <-- 4
 void addConstraint(Constraint& c);
};

#endif // #ifndef CONSTRAINTMAP_H

(1)a forward declaration

(2)Needs definitions of QHash and QString, but only the declaration of Constraint, because its a pointer.

(3)No problemits just a pointer.

(4)errorincomplete type

As you can see, as long as we use pointers or references, a forward declaration will suffice. The pointer dereferencing and member accessing operations are performed in the implementation file, which needs the full definition of all types it uses.

Example C.2. src/preprocessor/including.cpp

#include "constraintmap.h"

ConstraintMap map; <-- 1

/* redundant but harmless if #ifndef wrapped */
#include "constraintmap.h"

// Constraint p; <-- 2
#include 
Constraint q; <-- 3

(1)OkayConstraintMap already included.

(2)errorincomplete type

(3)Now it is a complete type.

Here are some guidelines to help decide whether you need a forward declaration or the full header file to #include in your header file:

• If ClassA derives from ClassB, the definition of ClassB must be known by the compiler when it processes the definition of ClassA. Therefore, the header file for ClassA must to the header file for ClassB.
• If the definition of ClassA contains a member that is an object of ClassD, the header file for ClassA must #include the header file for ClassD. If the definition of ClassA contains a function that has a parameter or a return object of ClassD, the header file for ClassA must #include the header file for ClassD.
• If the definition of ClassA only contains non-dereferenced ClassE pointers, then a forward declaration of ClassE is sufficient in the ClassA header file:

  class ClassE;
  

A class that is declared but not defined is considered an incomplete type. Any attempt to dereference a pointer or define an object of an incomplete type will result in a compiler error.^[2]

^[2] The actual error message may not always be clear, and with QObjects, it might come from the MOC-generated code rather than your own code.

The implementation file, classa.cpp, for ClassA should #include "classa.h" and also #include the header file for each class that is used by ClassA (unless that header file has already been included in classa.h). All pointer dereferencing should be performed in the .cpp file. This helps reduce dependencies between classes and improves compilation speed.

A .cpp file should never #include another .cpp file. A header file should #include as few other header files as possible so that it can be included more quickly and with fewer dependencies. A header file should always be #ifndef wrapped to prevent it from being included more than once.

Circular Dependencies

Whenever one file #includes another, there is a strong dependency created between the files. When a dependency like this exists between header files, it cannot be bidirectional: The preprocessor is unable to cope with a circular dependency between header files, where each one #includes the other. One of the #include statements must be replaced by a forward class declaration.

Forward declarations help remove circular dependencies between classes and, in the process, enable bidirectional relationships to exist between them.