Organizing Source Files in C++ Projects

A C++ program is usually spread across several files, and some of those files are headers. Before reading any code, a useful question to ask is what a header file is for. The source material answers this directly: header files are used to represent interfaces and to emphasize logical structure. In other words, a header tells the reader what a part of the program offers, while the details of how it works live somewhere else.

The rest of this article follows one small idea from start to finish. You will see what a header promises, how its matching source file fulfills that promise, and what kinds of code should stay out of the header so that it keeps describing the interface rather than the implementation.

The source material draws a clear split between two roles. The header sits on the interface side and declares what is offered. The source file sits on the implementation side and defines the functions the header declares. Reading the header gives the logical structure of the component; reading the source gives the work itself.

Notice what the header column contains: names, parameter types, and return types. These are the things another file needs in order to call the function. The source column contains what makes the function do its job. A reader of the header learns how to use the component without learning how it is built.

A header that declares functions needs someone to define them. Think of a declaration as a promise about what a function looks like, and a definition as the code that keeps that promise. The header makes the promise visible to everyone; the source file keeps it. The example below is a small two-file project written to illustrate this split. It is not taken from the source material.

The reader of geometry.h learns that add exists and how to call it. The reader of geometry.cpp learns that a + b is the work. Splitting the two this way is exactly what the source means by headers emphasizing logical structure: the header shows the component's shape, and the source file fills in the detail.

The source material gives a clear rule: the source file that implements the functions declared in a header should include that header, using the #include directive. This means geometry.cpp begins with #include "geometry.h", even though it is the file that defines add. The implementation file therefore carries the header's declarations with it.

The reason this matters is that the definitions the implementation file writes can be checked against those declarations. Because the definition of add is compiled in the same file that sees the declaration, the definition and the declaration are written side by side and must agree with each other.

To trace the whole project, add a third file that uses add. This file, main.cpp, is also a generated illustration. It includes the header, not the implementation, because it only needs to know what add offers.

Read the diagram from top to bottom. The header is the shared description that both geometry.cpp and main.cpp include. The compiler checks geometry.cpp against the declaration it includes. The compiler then handles main.cpp, which relies on the same declaration. The linker is where the call in main.cpp is connected to the definition in geometry.cpp, so the final program gets its add function from the implementation file, not from the header.

The source states that non-inline function definitions should be avoided in header files. The distinction matters because a header describes the interface, and a non-inline definition places a full implementation inside the header. The source gives the rule without elaborating its reasoning, so the practical habit to take from it is to keep full non-inline function bodies in source files and to keep headers focused on declarations.

Consider what would happen if the body of add were written in geometry.h instead. A reader opening the header would now see the implementation, which blurs the line between what the component offers and how it works. The header would also no longer be a short statement of structure. Keeping the body out of the header preserves the separation the rest of this article has been tracing.