summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2015-01-15 15:20:09 -0800
committerJunio C Hamano <gitster@pobox.com>2015-01-15 15:42:50 -0800
commit412cb2ec1302364aba862b183210249c2ca7d44e (patch)
tree621eab7ccf12e863a36eb7aca2f573134f982774
parent897f964c0dce8e7cc2cc53bb19b83cadce106773 (diff)
downloadgit-412cb2ec1302364aba862b183210249c2ca7d44e.tar.gz
CodingGuidelines: clarify C #include rulesjc/coding-guidelines
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>
-rw-r--r--Documentation/CodingGuidelines11
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