[MPlayer-cvslog] Multiple header inclusions -was: license wars!

[Ivan Kalvachev]

On Jan 2, 2008 10:13 PM, Diego Biurrun <diego at biurrun.de> wrote:
> I actually did have a look at every single source file and apart from
> noticing tons of missing or wrong multiple inclusion guards...

Before you go on rampage with the inclusion guard in mplayer.
There is old policy (I think somebody referred to it as BSD) that
handles the inclusion of header files. In short the header files must
not include other header files and the .c file have to explicitly
include all headers in the correct order.

Multiple inclusion guards are to be used when the library is going to
be used from another program that doesn't know the requirements of the
library.
When headers are internal it is good policy to include them only once
and threat multiple inclusions as bugs.

One artificial (but possible) example:

#include "config.h"
#include "mp_msg.h"
#define _GNU_SOURCE
#include <stdio.h>
int main(){
return (int)asprintf("Hello World\n");
}

If for some reason "mp_msg.h" includes <stdio.h> , it would define the
standard posix capabilities and would enable its own multiple
inclusion guard. After that the definition of _GNU_SOURCE would not
have any effect as the guard would prevent redefinition. The asprintf
function would remain undefined.

I agree that we shouldn't use gnu extensions, and that they should be
defined in separate header file instead in the standard headers, but
this is not the point here.

Same situation could happen and with our own conditions. Of course
there is nothing fatal in it, in the above example can be fixed by
reordering the definition and inclusions.

But it won't be obvious why that code doesn't work and the other does!

Another problem that arise when headers include other headers is that
it encourages sloppy programming. Coder could figure out that he can
include only one header and would get second for free. After time
somebody else would clean the first header in a way that removes
second header inclusion.
This would cause the original program to fail compilation without
having any modifications in it. This situation is quite common among
external kernel modules e.g. kqemu-1.3.0pre11 can't be compiled on
2.6.23 kernel, without adding missing #include <sched.h>.

Making header loading order obvious makes behavior tracking a lot easier.
As headers are included only once,  second inclusion could be done
only by another header and it should be treated as bug.

If you really want to put multiple inclusion guards then you'd better
make them call #error if header is included twice.