7. Header Files

Lesson 7 extension · follow the declaration through the build

Which translation unit knows the promise, and where is it kept?

Dividing a project into neatly named files is visible organisation. It is not yet evidence that the files form a correct program. The stronger test is whether each separately compiled source file sees the declarations it needs and whether the complete build supplies the required definitions without contradiction.

An #include directive does not link a header to an implementation file. During preprocessing, the header's tokens become available within the including source. That result is compiled as one translation unit. Other source files are processed and compiled separately, and the linker later combines their object files and resolves references between them.

This model explains why adding a header can remove a compiler error while leaving a linker error untouched. The declaration may now be visible, so the compiler can check the call. If no linked object file contains the required definition, the program is still incomplete. Different stage, different evidence.

Build one function through three files

The header states the interface shared by its users:

#ifndef CPP_PROGRAMMING_SCORE_H_INCLUDED
#define CPP_PROGRAMMING_SCORE_H_INCLUDED

int add_bonus(int score, int bonus);

#endif

The implementation source includes that same declaration and supplies the ordinary function definition:

#include "score.h"

int add_bonus(int score, int bonus) {
    return score + bonus;
}

The application source includes the interface and calls the operation:

#include "score.h"

#include <iostream>

int main() {
    std::cout << add_bonus(40, 2) << '\n';
}

Preprocess and compile score.cpp, and one object file contains the definition of add_bonus. Preprocess and compile main.cpp, and another object file contains a reference to that operation after checking the call against the declaration from score.h. Link the two object files, and the reference can be matched to the definition.

The header is not compiled once as a third implementation unit. Its guarded contents are processed inside score.cpp's translation unit and again inside main.cpp's translation unit. Both source files therefore check against the same written declaration, while only score.cpp supplies the ordinary definition.

An include guard controls repetition within one translation unit

The macro guard in score.h prevents its guarded contents from being processed repeatedly during one translation unit's preprocessing. This matters when several include paths lead back to the same header. It does not make the header appear only once across the entire program. main.cpp and score.cpp each perform their own preprocessing.

That boundary explains what guards can and cannot fix. A repeated class definition inside one translation unit may be prevented by the guard. An ordinary non-inline function definition placed in a guarded header can still be reproduced in several translation units, because each unit gets one copy. The guard has worked and the program may still violate the One Definition Rule.

#pragma once is a convenient and widely implemented alternative for preventing repeated processing of a header. It is not a directive required by the C++ standard. A conventional macro guard remains the portable course mechanism. Whichever form a project chooses, consistency is useful; neither form repairs a misplaced definition.

The interface must include what its own declarations require

A header should support its declarations without depending on a fortunate include order in some unrelated source file. If a declaration requires a complete standard-library type, include the standard header that provides it. Compiling a tiny source file that includes only the header is a practical test of that self-sufficiency.

A forward declaration is appropriate when the incomplete type is sufficient for the declaration being written. A function declaration taking a class by reference can often name a forward-declared class. A data member stored by value requires the complete class definition because its size and layout must be known. The decision is not "fewer includes are always better". The decision is whether the interface needs the complete definition.

The same restraint applies to definitions. An ordinary non-inline function usually belongs in one implementation source file. The inline rules permit suitable identical definitions in multiple translation units; the keyword does not promise that the compiler will substitute the body at each call. Template definitions are commonly kept visible in headers because their instantiation model requires that visibility. Lesson 23 will deal with that mechanism rather than using it as an exception that obscures today's rule.

Classify the failure before changing the boundary

Remove #include "score.h" from main.cpp and the call has no declaration in sight. That is a compilation problem in the main.cpp translation unit. Restore the header but omit the object file built from score.cpp, and both source files may compile before the linker reports that the definition is missing. Move the function definition into the header and include it from both source files, and the build can acquire competing definitions.

These failures may all mention add_bonus, but they do not ask for the same repair. Adding another include to an undefined-reference error does not manufacture the missing linked definition. Adding an include guard to an ordinary definition reproduced across translation units does not make that definition unique. Read the stage first, then account for the declaration and definition.

Dependencies are part of the design

Every include creates a source dependency. A large public header that exposes implementation details makes more translation units depend on those decisions and can increase the amount of code rebuilt after a change. Build time is visible, but it is still a consequence. The architectural question is whether callers genuinely need the exposed information.

A cyclic include is likewise a symptom before it is a diagnosis. Forward declarations can break some textual cycles when incomplete types are sufficient. They cannot decide whether two components should know about each other. If type A's public interface requires type B and type B's public interface requires type A, draw both arrows and explain the responsibilities. The preprocessor can be made quiet while the dependency direction remains confused.

Run three deliberate failures

Use the three-file example and change one fact at a time. First remove the include from main.cpp. Next restore it and leave score.cpp's object file out of the link. Finally place the ordinary definition in the header and include that header from both source files. Before each build, predict the first failing stage and the declaration or definition account that will be incomplete.

Record the actual diagnostic beside the prediction, then restore the correct boundary and perform a clean build. If your explanation is only "the header was wrong", continue. State which translation unit saw which declaration, where the definition existed, and what the linker was asked to combine. Headers organise source, but their real value is that they make a shared promise available wherever that promise must be checked.