On 08/27/2010 09:35 AM, Mats Kindahl wrote:
> 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.
>
>
>
