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

Le mercredi 15 avril 2009, Jeff King a écrit :

On Tue, Apr 14, 2009 at 12:34:33AM +0200, Christian Couder wrote:

quoted

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