module through its header file ensures that only a single set of declarations needs to be maintained, and helps enforce the One-Defini-
tion Rule.
Guideline #4. No namespace using statements are allowed at the top level in a header file. See the Handout Using “using” for an
explanation and guidelines. Usually you should be using fully qualified names in a header file, such as “std::ostream.”
Guideline #5. The header file contains only declarations, templates, and inline function definitions, and is included by the .cpp
file for the module. Put structure and class declarations, function prototypes, and global variable extern declarations, in the .h file; put
the function definitions and global variable definitions and initializations in the .cpp file. The .cpp file for a module must include the .h
file; 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), the compiler must have the full definitions available in order
to instantiate the template, and so all templated function definitions must appear in the header file. Similarly, the compiler must have
the full definitions available for ordinary (nonmember) functions that need to be inlined, so the function definitions will also appear
(declared inline) in the header file (this is unusual, and normally won’t happen until late in project development during performance
tuning).
Guideline #6. Set up global variables for a module with an extern declaration in the header file, and a defining declaration in the
.cpp file. For global variables that will be known throughout the program, place an extern declaration in the .h file, as in:
extern int g_number_of_entities;
The other modules #include only the .h file. The .cpp file for the module must include this same .h file, and near the beginning of the
file, a defining declaration should appear - this declaration both defines and initializes the global variables, as in:
int g_number_of_entities = 0;
Of course, some other value besides zero could be used as the initial value, and static/global variables are initialized to zero by default;
but initializing explicitly to zero is customary because it marks this declaration as the defining declaration, meaning that this is the
unique point of definition. Note that different C compilers and linkers will allow other ways of setting up global variables, but this is
the accepted C++ method for defining global variables and it also works for C to ensure that the global variables obey the One Defini-
tion Rule.
Guideline #7. Keep a module’s internal declarations out of the header file. 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 file 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 file, put their definitions or decla-
rations at convenient points in the .cpp file and do not mention them in the .h file.
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 file with other class declarations. It is
better is to place their declarations in the .cpp file just ahead of the function that uses them.
Furthermore, declare these internal global variables and functions static in the .cpp file 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 file), so declaring these as static is redundant and should not be done.
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 #8. Put declarations in the narrowest scope possible in the header file. Double-check Guideline #5 and make sure that a
declaration belongs in the header file rather than the .cpp file for a module. If it does belong in the header file, place the declaration in
the private section of a class if possible, followed by the protected section, followed by the public section of a class. Do not make it
top-level in the header file unless it really needs to be that way.
For example, a typedef or type alias declaration that is only used within a class's member functions should be declared in the pri-
vate section of the class. If the client code needs to use the declaration, place the it in the public section of the class. Don't place it at