List:Internals« Previous MessageNext Message »
From:Mats Kindahl Date:August 27 2010 7:39am
Subject:[STYLE] Self-sufficient header files
View as plain text  

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.


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,
""). 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
      "", which may not be the same as the author of
          o It would require the author of "" to read
            "my_header.h" and realize that "my_other.h" is required.
          o It would further require the author of "" 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
several developers.

Just my few cents,
Mats Kindahl
[STYLE] Self-sufficient header filesMats Kindahl27 Aug
  • Re: [STYLE] Self-sufficient header filesKonstantin Osipov8 Sep
    • Re: [STYLE] Self-sufficient header filesMichael Widenius16 Sep
      • Re: [STYLE] Self-sufficient header filesTor Didriksen16 Sep
      • Re: [STYLE] Self-sufficient header filesKonstantin Osipov16 Sep
        • Re: [STYLE] Self-sufficient header filesMats Kindahl16 Sep