Difference between revisions of "Cpp Coding Standards/HEADERS"
From Apache OpenOffice Wiki
m (→Internal Include Guards <span id="IncGuards">(IncGuards)</span>: removed underscore in include-guard) |
(some improvements) |
||
| Line 8: | Line 8: | ||
When included a header file should be self sufficient and minimal. | When included a header file should be self sufficient and minimal. | ||
| − | * Include definitions for superclasses | + | * Include definitions for superclasses, data members, typedefs, macros, types denoted in exception-specifications, ... |
| − | * Create forward declarations for everything else | + | * Create forward declarations for everything else (but note that this introduces unwanted coupling, when for example a template declaration is later on extended with defaulted parameters, or a struct definition is replaced with a typedef) |
* Include the definition as late as possible, this helps reduce physical dependencies | * Include the definition as late as possible, this helps reduce physical dependencies | ||
| Line 61: | Line 61: | ||
// Yes, use internal include guards | // Yes, use internal include guards | ||
| − | #ifndef | + | #ifndef INCLUDED_FOO_HXX |
| − | #define | + | #define INCLUDED_FOO_HXX |
// No include guards here | // No include guards here | ||
Revision as of 15:31, 10 May 2007
Topic-Id: HEADERS
What to do or do not with header files.
Contents
Summary
Self Sufficient and Minimal (Self)
When included a header file should be self sufficient and minimal.
- Include definitions for superclasses, data members, typedefs, macros, types denoted in exception-specifications, ...
- Create forward declarations for everything else (but note that this introduces unwanted coupling, when for example a template declaration is later on extended with defaulted parameters, or a struct definition is replaced with a typedef)
- Include the definition as late as possible, this helps reduce physical dependencies
// Foo.hxx
// Superclass and data member
#include "Super.hxx"
#include "Data.hxx"
// Forward declarations
class Param;
// This does not need a class definition
Param doSomething1(Param aParam);
class Foo : public Super
{
public:
// This does not need a class definition either
Param doSomething(Param aParam);
private:
Data mData;
};
// Anotherfile.cxx #include "Foo.hxx" #include "Param.hxx" // Now we need the definition ... Param p; p = doSomething1(p); // Error without the definition
Include Directly (IncDirect)
Include the header files for all types you need directly, not via another file.
Precompiled headers (IncPCH)
- The first statement in each cxx files should be the inclusion of precompiled headers. There must be no other includes, no definitions and no include guards around the include statement. Forget this for a new file and you break the build.
- Assume the precompiled header file is empty and include all your headers normally.
#include "precompiled_foo.hxx" // May or may not contain includes for Foo.hxx and Bar.hxx #include "Foo.hxx" #include "Bar.hxx"
Internal Include Guards (IncGuards)
Internal include guards are good but don't use the external ones. They add a lot of noise for a non-existent benefit.
// Foo.hxx // Yes, use internal include guards #ifndef INCLUDED_FOO_HXX #define INCLUDED_FOO_HXX // No include guards here #include "Superclass.hxx" ... #endif
// Bar.cxx // No include guards here #include "Bar.hxx" #include "Foo.hxx" #include "Baz.hxx"
