Re: [PATCH] Documentation/CodingGuidelines: improve header includes rules

[Christian Couder <chriscool@tuxfamily.org>]

Le mercredi 15 avril 2009, Jeff King a écrit :
> On Tue, Apr 14, 2009 at 12:34:33AM +0200, Christian Couder wrote:
> > 	- The third one means that for example if we have "revision.h"
> > 	that includes "diff.h" and "commit.h", then it's ok to include
> > 	"revision.h" in a C file, only if at least one feature from
> > 	"revision.h" is actually used in the C file.
> >
> > 	It is not ok to include "revision.h" if features from "diff.h"
> > 	and "commit.h" are used but no feature from "revision.h" is
> > 	used.
>
> Why? I thought the guiding principle mentioned earlier was "don't waste
> programmers' time figuring out what should and shouldn't be included".
>
> Sure, I would not expect somebody to include a header that is totally
> unrelated, but it seems that most of the source files lazily include
> cache.h just to get "everything".

The third rule is:

+ - After the first #include in a C file, only header files containing
+   features that are actually used in the C file should be included.
+   (This means that it is not ok to include an header file only
+   because this header file includes other header files with features
+   that are used in the C file.)

So this rule is only for #include after the first one, and "cache.h" should 
be the first one if it is included.

I added this rule because we need a little sanity too and it can be 
misleading to see an include of some feature when in fact no features from 
the include are used.

> Stripping unnecessary includes doesn't even speed up compilation, as our
> Makefile overspecifies the header dependencies anyway.

Perhaps the dependencies will not be overspecified one day, and I think it 
should at least speed up a little bit compilation of the C file where 
unnecessary includes have been stripped. And anyway it looks simpler and 
does not mislead into thinking that some feature are used when they are 
not.

Best regards,
Christian.