Header files must begin and end with multiple-inclusion protection. [header-guards] #ifndef PACKAGE_CLASS_H #define PACKAGE_CLASS_H // The text of the header goes in here ... #endif // PACKAGE_CLASS_H Header files are often included many times in a program. Because C++ does not allow multiple definitions of a class, it is necessary to prevent the compiler from reading the definitions more than once. The include guard should include both the package name and class name, to ensure that is unique. Don't start the include guard name with an underscore; such names are reserved to the compiler. Be careful to use the same string in the ifndef and the define . It's useful to get in the habit of using copy/paste here rather than retyping the string. Some compilers support an extension #pragma once that has similar functionality. A long time ago, this was sometimes faster, as it allowed the compiler to skip reading headers that have already been read. However, modern compilers will automatically do this optimization based on recognizing header guards. As #pragma once is nonstandard and has no compelling advantage, it is best avoided. In some rare cases, a file may be intended to be included multiple times, and thus not have an include guard. Such files should be explicitly commented as such, and should usually have an extension other than ``.h''; ``.def'' is sometimes used for thus purpose.

Use forward declaration instead of including a header file, if this is sufficient. [forward-declarations] class Line; class Point { public: // Distance from a line Number distance(const Line& line) const; }; Here it is sufficient to say that Line is a class, without giving details which are inside its header. This saves time in compilation and avoids an apparent dependency upon the Line header file. Be careful, however: this does not work if Line is actually a typedef (as is the case, for example, with many of the xAOD classes).

Each header file must contain the declaration for one class only, except for embedded or very tightly coupled classes or collections of small helper classes. [one-class-per-source] This makes your source code files easier to read. This also improves the version control of the files; for example the file containing a stable class declaration can be committed and not changed any more. Some exceptions: Small classes used as helpers for another class should generally not go in their own file, but should instead be placed with the larger class. Sometimes several very closely related classes may be grouped together in a single file; in that case, the files should be named after whichever is the ``primary'' class. A number of related small helper classes (not associated with a particular larger class) may be grouped together in a single file, which should be given a descriptive name. An example of the latter could be a set of classes used as exceptions for a package.

Implementation files must hold the member function definitions for the class(es) declared in the corresponding header file. [implementation-file] This is for the same reason as for the previous item.

Ordering of #include statements. [include-ordering] #include directives should generally be listed according to dependency ordering, with the files that have the most dependencies coming first. This implies that the first #include in a ``.cxx'' file should be the corresponding ``.h'' file, followed by other #include directives from the same package. These would then be followed by #include directives for other packages, again ordered from most to least dependent. Finally, system #include directives should come last. // Example for CaloCell.cxx // First the corresponding header. #include "CaloEvent/CaloCell.h" // The headers from other ATLAS packages, // from most to least dependent. #include "CaloDetDescr/CaloDetDescrElement.h" #include "SGTools/BaseInfo.h" // Headers from external packages. #include "CLHEP/Geometry/Vector3D.h" #include "CLHEP/Geometry/Point3D.h" // System headers. #include <cmath> Ordering the #include directives in this way gives the best chance of catching problems where headers fail to include other headers that they depend on. Some old guides recommended testing on the C++ header guard around the #include directive. This advice is now obsolete and should be avoided. // Obsolete --- don't do this anymore. #ifndef MYPACKAGE_MYHEADER_H # include "MyPackage/MyHeader.h" #endif The rationale for this was to avoid having the preprocessor do redundant reads of the header file. However, current C++ compilers do this optimization on their own, so this serves only to clutter the source.