Re: Unused #include statements

[Jeff King <peff@peff.net>]

On Thu, Jan 15, 2015 at 10:50:45AM -0800, Junio C Hamano wrote:

> So the rule might be:
> 
>  - The first #include in C files, except in platform specific
>    compat/ implementations, must be either git-compat-util.h,
>    cache.h or builtin.h.
> 
>  - A C file must directly include the header files that declare the
>    functions and the types it uses, except for the functions and
>    types that are made available to it by including one of the
>    header files it must include by the previous rule.

Yeah, that makes sense (and is what I took away from the existing rule
in CodingGuidelines, but I agree what is there is not very rigorous).

> Optionally, 
> 
>  - A C file must include only one of "git-compat-util.h", "cache.h"
>    or "builtin.h"; e.g. if you include "builtin.h", do not include
>    the other two, but it can consider what is availble in "cache.h"
>    available to it.
> 
> Thoughts?  I am not looking forward to a torrent of patches whose
> sole purpose is to make the existing C files conform to any such
> rule, though.  Clean-up patches that trickle in at a low rate is
> tolerable, but a torrent is too distracting.

I don't think the "optionally" one above is that necessary. Not because
I don't agree with it, but because I do not know that we want to get
into the business of laying out every minute detail and implication.
The CodingGuidelines document is meant to be guidelines, and I do not
want to see arguments like "well, the guidelines do not explicitly
_disallow_ this, so you must accept it or add something to the
guideline". That is a waste of everybody's time.

A general philosophy + good taste (from the submitter and the
maintainer) should ideally be enough. And hopefully would stop a torrent
of "but this file doesn't conform to the letter of CodingGuidelines!".
Maybe it does not, but if there is no tangible benefit besides blindly
following some rules, it is not worth the precious time of developers.

Which isn't to say we shouldn't clarify the document when need be. But I
think what I quoted at the top already is probably a good improvement
over what is there.

-Peff