Subject: Re: Doxygen generated documentation
To: Christos Zoulas <>
From: Rhialto <>
List: tech-userlevel
Date: 05/24/2005 16:01:52
On Mon 23 May 2005 at 18:10:24 -0400, Christos Zoulas wrote:
> There are instances where we are not allowed to make headers
> idempotent (assert.h) and others where we cannot make headers self
> sufficient because of namespace pollution issues. We strive to make
> headers standards compliant, and that sometimes this gets in the
> way of convenience. I have seen many examples where programs fail
> to include required headers (such as <signal.h> when using signals),
> just because it happens to work on operating systems that include
> the kitchen-sink when you include a popular header (such as
> <unistd.h>). This include-all approach actually hurts portability.

I agree in principle that whenever possible, a header file should be
self-sufficient. By that I mean that a source file containing nothing

    #include <foo.h>

should compile without errors. If there is really a standards case which
prohibits that, then that has precedence, but I doubt it occurs often.
It is probably more the case that including something else first causes
some different behaviour. While that is in general to be frowned upon
too, I also make an exception for strict standards compliance.

My other rule for #including is that you should explicitly include
header files from which you use something, even if some other header
file already includes it (and even if you know that).

Note that this is far-from an include-all approach; I would call it an
include-precisely-what-you-use approach and in the long run it seems
like the most portable option to me.

On the order of the #inludes, my rule is to go from general to specific,
i.e. include standard C headers first, then Unix headers, then project
headers. Within each category I also prefer a sort of bottom-up order,
so <unistd.h> seems to go before <stdio.h>.

> christos
___ Olaf 'Rhialto' Seibert                            --  rhialto/at/
\X/ Hi! I'm a signature virus! Copy me to your .signature to help me spread!