From: Mats Kindahl
Date: August 27 2010 7:35am
Subject: [STYLE] Self-sufficient header files
List-Archive: http://lists.mysql.com/internals/38036
Message-Id: <4C776AA5.3030106@oracle.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

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.