C.2. The Preprocessor: For #including Files

C.2. The Preprocessor: For `#including` Files
	Appendix C. Development Tools

C.2. The Preprocessor: For `#including` Files

[ fromfile: preprocessor.xml id: preprocessor ]

In C++, code reuse is indicated by the presence of a preprocessor directive, #include, at the top of source code files.

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

#ifndef CONSTRAINTMAP_H
#define CONSTRAINTMAP_H

#include <QHash>
#include <QString>

class Constraint;                                           

class ConstraintMap : public QHash<QString, Constraint*> {  

private:
    Constraint* m_Constraintptr;                            
    Constraint m_ConstraintObj;                             
    void addConstraint(Constraint& c);                      
};
#endif        //  #ifndef CONSTRAINTMAP_H

	Forward declaration.
	Needs definitions of `QHash` and `QString`, but only the declaration of Constraint, because it's a pointer.
	No problem, it's just a pointer.
	Error: incomplete type.
	Using forward declaration.

As you can see, inside function parameter lists, you can use pointers or references to classes which were only declared, not defined.
The pointer dereferencing and member accessing operations are performed in the implementation file shown in Example C.3.
There, you must #include the full definitions of each type it uses.

Example C.3. src/preprocessor/constraintmap.cpp

#include "constraintmap.h"

ConstraintMap map;              
#include "constraintmap.h"      

Constraint* constraintP;        

Constraint p;                   
#include <constraint.h>
Constraint q;                   

void ConstraintMap::addConstraint(Constraint& c) {
    cout << c.name();           
}

	Okay, ConstraintMap is already included.
	Redundant but harmless if #ifndef wrapped.
	Using forward declaration from constraintmap.h.
	Error: incomplete type.
	Now it is a complete type.
	Complete type required here.

To minimize the number of "strong dependencies" between header files, you should declare classes instead of #including header files whenever posible.

- 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 #include 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 nondereferenced ClassE pointers or references, 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 results in a compiler error.^[91]

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).
Any 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 versus Bidirectional Relationships

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 cannot 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.

^[91]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.


C.1. `make` and `Makefile`		C.3. Understanding the Linker