diff options
| author |  Junio C Hamano <gitster@pobox.com> | 2015-01-15 15:20:09 -0800 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2015-01-15 15:42:50 -0800 |
| commit | 412cb2ec1302364aba862b183210249c2ca7d44e (patch) | |
| tree | 621eab7ccf12e863a36eb7aca2f573134f982774 /Documentation | |
| parent | CodingGuidelines: avoid "test <cond> -a/-o <cond>" (diff) | |
| download | tgif-412cb2ec1302364aba862b183210249c2ca7d44e.tar.xz | |
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>
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 11 |
1 files changed, 8 insertions, 3 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 4d90c77c7b..ae8b42f3be 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -328,9 +328,14 @@ For C programs: - When you come up with an API, document it. - - The first #include in C files, except in platform specific - compat/ implementations, should be git-compat-util.h or another - header file that includes it, such as cache.h or builtin.h. + - The first #include in C files, except in platform specific compat/ + implementations, must be either "git-compat-util.h", "cache.h" or + "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 or perl first, so that changes in semantics can be easily |