CodingGuidelines: clarify C #include rules

Even though "advice.h" includes "git-compat-util.h", it is not sensible to have it as the first #include and indirectly satisify the "You must give git-compat-util.h a clean environment to set up feature test macros before including any of the system headers are included", which is the real requirement. Because: - A command that interacts with the object store, config subsystem, the index, or the working tree cannot do anything without using what is declared in "cache.h"; - A built-in command must be declared in "builtin.h", so anything in builtin/*.c must include it; - These two headers both include "git-compat-util.h" as the first thing; and - Almost all our *.c files (outside compat/ and borrowed files in xdiff/) need some Git-ness from "cache.h" to do something Git-ish. let's explicitly specify that one of these three header files must be the first thing that is included. Any of our *.c file should include the header file that directly declares what it uses, instead of relying on the fact that some *.h file it includes happens to include another *.h file that declares the necessary function or type. Spell it out as another guideline item. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Jan 15, 2015 at 15:20 UTC 412cb2ec1302364aba862b183210249c2ca7d44e
1 file changed +8 -3
Documentation/CodingGuidelines
+8 -3
@@ -328,9 +328,14 @@ For C programs:
328
329 - When you come up with an API, document it.
330
331 - - The first #include in C files, except in platform specific
332 - compat/ implementations, should be git-compat-util.h or another
333 - header file that includes it, such as cache.h or builtin.h.
331 + - The first #include in C files, except in platform specific compat/
332 + implementations, must be either "git-compat-util.h", "cache.h" or
333 + "builtin.h". You do not have to include more than one of these.
334 +
335 + - A C file must directly include the header files that declare the
336 + functions and the types it uses, except for the functions and types
337 + that are made available to it by including one of the header files
338 + it must include by the previous rule.
339
340 - If you are planning a new command, consider writing it in shell
341 or perl first, so that changes in semantics can be easily