Every header file should be self-sufficient in the sense that for a
header file my_header.h, the following should compile without errors:
An exception is made for generated files, for example, those generated
by Yacc and Lex, since it is not possible to re-write the generators to
produce "correct" files.
Source files should not include more than necessary, in particular, they
should not include header files for features that are not used in that
file. In the case that a header file (say, "my_header.h") uses some
feature (for example, a type, class, or function) from another header
file (say "my_other.h"), it is therefore necessary to ensure that this
feature is defined when "my_header.h" is needed in a source file (say,
"my_code.cc"). There are two ways to accomplish this:
1. Include first "my_other.h" and then "my_header.h" in every source
file where "my_header.h" is necessary.
2. Include "my_other.h" in "my_header.h".
Method 1 has a few disadvantages:
* It places an unnecessary burden on the author of the source file
"my_code.cc", which may not be the same as the author of
o It would require the author of "my_code.cc" to read
"my_header.h" and realize that "my_other.h" is required.
o It would further require the author of "my_code.cc" to read
"my_other.h" to realize what is needed there, and this
applies recursively to every file in the include chain.
* If the definitions inside "my_header.h" should change, it is
necessary to change all the source files that use "my_header.h".
For a closed system, this is possible, but in the case that there
are third-party users of the header file, it is not possible.
* It would be possible to restrict this rule to only cover header
files that make up the external interface, but since there is no
reasonable advantage to have such a restriction, I propose that
the rule is kept as simple as possible.
Method 2 has one disadvantage:
* The compile has to read frequently included files several times,
which might impact compile time.
o Considering the size of the paging system on most machines
today, I believe that this is a non-problem since frequently
included header files will be available in the page cache.
o Designing coding style rules for compilation speed is a bad
To implement this proposal, it is necessary to turn each and every
header file self-sufficient. This cannot be done as a single patch,
since it would take a considerable time to implement but should rather
be done by taking one file at a time. It will be necessary to split some
files into several header files because of internal dependencies.
Placing the extra burden on every developer that changes a header file
to make it self-sufficient is not reasonable. The implementation of this
guideline requires a dedicated effort, but it can be distributed over
Just my few cents,