From: Mats Kindahl
Date: August 27 2010 7:39am
Subject: [STYLE] Self-sufficient header files
List-Archive: http://lists.mysql.com/internals/38037
Message-Id: <4C776BA6.7010501@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.


Implementation
==========

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