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>
This commit is contained in:
Junio C Hamano 2015-01-15 15:20:09 -08:00
Родитель 897f964c0d
Коммит 412cb2ec13
1 изменённых файлов: 8 добавлений и 3 удалений

Просмотреть файл

@ -328,9 +328,14 @@ For C programs:
- When you come up with an API, document it. - When you come up with an API, document it.
- The first #include in C files, except in platform specific - The first #include in C files, except in platform specific compat/
compat/ implementations, should be git-compat-util.h or another implementations, must be either "git-compat-util.h", "cache.h" or
header file that includes it, such as cache.h or builtin.h. "builtin.h". You do not have to include more than one of these.
- 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.
- If you are planning a new command, consider writing it in shell - If you are planning a new command, consider writing it in shell
or perl first, so that changes in semantics can be easily or perl first, so that changes in semantics can be easily