Proposal
======
Every header file should be self-sufficient in the sense that for a
header file my_header.h, the following should compile without errors:
#include "my_header.h"
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.
Rationale
======
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
"my_header.h".
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
idea.
