From: Mats Kindahl
Date: August 27 2010 7:40am
Subject: Ignore this, incomplete [Was: [STYLE] Self-sufficient header files]
List-Archive: http://lists.mysql.com/internals/38038
Message-Id: <4C776BF9.1030005@oracle.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

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.
>
>
>