Header C++ File Guidelines
David Kieras, EECS Dept., University of Michigan
Prepared for EECS 381, Fall 2006
This document is similar to the corresponding document for C, but includes some material specic to C++.
What should be in the header les for a complex project? C and C++ programs normally take the form of a collection of separately
compiled modules. Thanks to the separate compilation concept, as a big project is developed, an new executable can be built rapidly
if only the changed modules need to be recompiled.
In C++, the contents of a module consist of structure type (struct) declarations, class declarations, global variables, and functions. The
functions themselves are normally dened in a source le (a .cpp le). Except for the possible exception of the main module, each
source (.cpp) le has a header le (a .h le) associated with it that provides the declarations needed by other modules to make use of
this module. The idea is that other modules can access the functionality in module X simply by #including the X.h header le, and
the linker will do the rest. The code in X.cpp needs to be compiled only the rst time or if it is changed; the rest of the time, the linker
will link Xs code into the nal executable without needing to recompile it, which enables the Unix make utility and IDEs to work
very efciently.
A well organized C++ program has a good choice of modules, and properly constructed header les that make it easy to understand
and access the functionality in a module. Furthermore, well-designed header les reduce the need to recompile the source les for
components whenever changes to other components are made. The trick is reduce the amount of coupling between components by
minimizing the number of header les that a modules header le itself #includes. On very large projects (where C++ is often used),
minimizing coupling can make a huge difference in build time.
The following guidelines summarize how to set up your header and source les for the greatest clarity and compilation convenience.
Guideline #1. Each module with its .h and .cpp le should correspond to a clear piece of functionality. Conceptually, a module is
a group of declarations and functions can be developed and maintained separately from other modules, and perhaps even reused in
entirely different projects. Dont force together into a module things that will be used or maintained separately, and dont separate
things that will always be used and maintained together. The Standard Library modules <cmath> and <string> are good examples of
clearly distinct modules.
Guideline #2. Always use include guards in a header le. The most compact form uses ifndef. Choose a guard symbol based
on the header le name, since these symbols are easy to think up and the header le names are almost always unique in a project. Follow the convention of making the symbol all-caps. For example Geometry_base.h would start with:
#ifndef GEOMETRY_BASE_H
#define GEOMETRY_BASE_H
and end with:
#endif
Guideline #3. All of the declarations needed to use a module must appear in its header le, and this le is always used to access
the module. Thus #including the header le provides all the information necessary for code using the module to compile and link correctly; the header le contains the public interface for the module. Furthermore, if module A needs to use module Xs functionality, it
should always #include X.h, and never contain hard-coded declarations for structs, classes, globals, or functions that appear in module X. Why? If module X is changed, but you forget to change the hard-coded declarations in module A, module A could easily fail
with subtle run-time errors that wont be detected by either the compiler or linker. This is a violation of the One-Denition Rule which
C++ compilers and linkers cant detect. Always referring to a module through its header le ensures that only a single set of declarations needs to be maintained, and helps enforce the One-Denition Rule.
Guideline #4. No using statements are allowed in a header le. See the Handout Using using for an explanation and guidelines. You should be using fully qualied names in a header le, such as std::ostream.
1
Guideline #5. The header le contains only declarations, templates, and inline function denitions, and is included by the .cpp
le for the module. Put structure and class declarations, function prototypes, and global variable extern declarations, in the .h le; put
the function denitions and global variable denitions and initializations in the .cpp le. The .cpp le for a module must include the .h
le; the compiler will detect any discrepancies between the two, and thus help ensure consistency.
Note that for templates, unless you are using explicit instantiations (rare) or the export facility (at this time even more rare), the
compiler must have the full denitions available in order to instantiate the template, and so all templated function denitions must
appear in the header le. Similarly, the compiler must have the full denitions available for ordinary (nonmember) functions that need
to be inlined, so the function denitions will also appear (declared inline) in the header le (this is unusual, and normally wont happen until late in project development during performance tuning).
For global variables, the declaration in the .h le should be an extern declaration, as in:
extern int g_number_of_entities;
The other modules #include only the .h le. The .cpp le for the module must include the .h le, and dene and initialize the global
variables, as in:
int g_number_of_entities = 3;
It is a common custom is to explicitly initialize a global variable to zero, even though in the case of zero it is technically redundant.
Note that different C compilers and linkers will allow other ways of setting up global variables, but this is the accepted C++ method
for dening global variables and it works for C as well.
Guideline #6. Keep a modules internal declarations out of the header le. Sometimes a module uses strictly internal components
that are not supposed to be accessed by other modules, or are not needed by other modules. The header le is supposed to contain the
public interface for the module, and everything else is supposed to be hidden from outside view and access. Thus, if you need class or
struct declarations, global variables, templates, or functions that are used only in the code in the .cpp le, put their denitions or declarations at points convenient in the .cpp le and do not mention them in the .h le.
One common example is special-purpose function object class declarations for use with the Standard Library algorithms. Often these
have absolutely no value outside the module, and so should not be simply tossed into the header le with other class declarations. It is
better is to place their declarations in the .cpp le just ahead of the function that uses them.
Furthermore, declare globals and functions static in the .cpp le to give them internal linkage (or put them into the unnamed
namespace). Constants declared as const variables with initialization automatically get internal linkage (even if they appear in a header
le), so static is not necessary.
This way, other modules do not (and can not) know about these declarations, globals, or functions that are internal to the module. The
internal linkage will enable the linker to help you enforce your design decision.
Guideline #7. Every header le A.h should #include every other header le that A.h requires to compile correctly, but no more.
What is needed in A.h: If another class or structure type X is used as a member variable of a class or structure type A, then you must
#include X.h in A.h so that the compiler knows how large the X member is. Similarly, if a class A inherits from class X which is declared in X.h, then you must #include X.h in A.h, so that the compiler knows the full contents of an A object. Do not include header
les that only the .cpp le code needs. E.g. <cmath> or <algorithm> is usually needed only by the function denitions - #include it in
.cpp le, not in the .h le.
Guideline #8. If an incomplete declaration of a type X will do, use it instead of #including its header X.h. If another struct or
class type X appears only as a pointer or reference type in the contents of a header le, then you should not #include X.h, but just
place an incomplete declaration of X (also called a "forward" declaration) near the beginning of the header le, as in:
class X;
See the handout Incomplete Declarations for more discussion of this powerful and valuable technique. Note that the Standard library
includes a header of incomplete declarations that often sufces for the <iostream> library, named <iosfwd>. #include <iosfwd> whenever possible, because the <iostream> header le is extremely large (giant templates!).
2
Guideline #9. A header le should compile correctly by itself. A header le should explicitly #include or forward declare everything
it needs. Failure to observe this rule can result in very puzzling errors when other header les or #includes in other les are changed.
Check your headers by compiling, all by itself, a test.cpp that contains nothing more than #include A.h. It should not produce
any compilation errors. If it does, then something has been left out - something else needs to be included or forward declared. Test all
the headers in a project by starting at the bottom of the include hierarchy and work your way to the top. This will help to nd and
eliminate any accidental dependencies between header les.
Guideline #10. The A.cpp le should rst #include its A.h le, and then any other headers required for its code. Always #include A.h rst to avoid hiding anything it is missing that gets included by other .h les. Then, if A's implementation code uses X, explicitly #include X.h in A.cpp, so that A.cpp is not dependent on X.h accidentally being #included somewhere else.
There is no clear consensus on whether A.cpp should also #include header les that A.h has already included. Two suggestions:
If the X.h le is a logically unavoidable requirement for the declaration in A.h to compile, then #including it in
A.cpp is redundant, since it is guaranteed to be included by A.h. So it is OK to not #include X.h in A.cpp, and will
save some compiler time (the compiler wont have to nd and open the .h le twice).
Always #including X.h in A.cpp is a way of making it clear to the reader that we are using X, and helps make sure
that Xs declarations are available even if the contents of A.h changes due to the design changes. E.g. maybe we
had a Thing member of a class at rst, then changed it to a Thing *, but still used members of Things in the implementation code. The #include of Thing.h saves us a compile failure. So it is OK to redundantly #include X.h in
A.cpp. Of course, if X becomes completely unnecessary, all of the #includes of X.h should be removed.
Guideline #11. Explicitly #include the headers for all Standard Library facilities used in a .cpp le. The Standard does not say
which Standard Library header les must be included by which other Standard Library headers, so if you leave one out, the code may
compile successfully in one implementation, but then fail in another. This is a gap in the Standard, justied weakly as giving implementers more freedom to optimize. Avoid future compile failures by always #including <algorithm>, <functional>, <iomanip>, etc.
whenever your code uses these components of the Standard Library.
Guideline #12. Never #include a .cpp le for any reason! This happens occasionally and it is always a mess. Why does it happen?
Sometimes you need to bring in a bunch of code that really should to be shared between .cpp les for ease of maintenance, so you put
it in a le by itself. Because the code does not consist of "normal" declarations or denitions, you know that putting it in a .h le is
misleading, so you are tempted to call it a .cpp le instead, and then write #include stuff.cpp.
But this causes instant confusion for other programmers and interferes with convenience in using IDEs, because .cpp les are normally separately compiled, so you have to somehow tell people not to compile this one .cpp le out of all the others. Furthermore, if
they miss this hard-to-document point, they get really confused because compiling this sort of odd le typically produces a million
error messages, making people think something mysterious is fundamentally wrong with your code or how they installed it. Conclusion: If it cant be treated like a normal header or source le, don't name it like one!
If you think you need to do something like this, rst make sure that there isn't a more normal way to share the code (such as simply
creating another module). If not, then name the special #include le with a different extension like ".inc" or ".inl".
3