doc: clarify the wording on <git-compat-util.h> requirement

The reason why we require the <git-compat-util.h> file to be the first header file to be included is because it insulates other header files and source files from platform differences, like which system header files must be included in what order, and what C preprocessor feature macros must be defined to trigger certain features we want out of the system. We tried to clarify the rule in the coding guidelines document, but the wording was a bit fuzzy that can lead to misinterpretations like you can include <xdiff/xinclude.h> only to avoid having to include <git-compat-util.h> even if you have nothing to do with the xdiff implementation, for example. "You do not have to include more than one of these" was also misleading and would have been puzzling if you _needed_ to depend on more than one of these approved headers (answer: you are allowed to include them all if you need the declarations in them for reasons other than that you want to avoid including compat-util yourself). Instead of using the phrase "approved headers", enumerate them as exceptions, each labeled with its intended audiences, to avoid such misinterpretations. The structure also makes it easier to add new exceptions, so add the description of "t/unit-tests/test-lib.h" being an exception only for the unit tests implementation as an example. Signed-off-by: Junio C Hamano <gitster@pobox.com> Acked-by: Kyle Lippincott <spectral@google.com> Acked-by: Elijah Newren <newren@gmail.com>

Junio C Hamano committed Feb 26, 2024 at 15:28 UTC 4e89f0e07cfba1155c012728e14f8362ab6a167f
1 file changed +35 -6
Documentation/CodingGuidelines
+35 -6
@@ -446,12 +446,41 @@ For C programs:
446 detail.
447
448 - The first #include in C files, except in platform specific compat/
449 - implementations and sha1dc/, must be either "git-compat-util.h" or
450 - one of the approved headers that includes it first for you. (The
451 - approved headers currently include "builtin.h",
452 - "t/helper/test-tool.h", "xdiff/xinclude.h", or
453 - "reftable/system.h".) You do not have to include more than one of
454 - these.
449 + implementations and sha1dc/, must be <git-compat-util.h>. This
450 + header file insulates other header files and source files from
451 + platform differences, like which system header files must be
452 + included in what order, and what C preprocessor feature macros must
453 + be defined to trigger certain features we expect out of the system.
454 + A collorary to this is that C files should not directly include
455 + system header files themselves.
456 +
457 + There are some exceptions, because certain group of files that
458 + implement an API all have to include the same header file that
459 + defines the API and it is convenient to include <git-compat-util.h>
460 + there. Namely:
461 +
462 + - the implementation of the built-in commands in the "builtin/"
463 + directory that include "builtin.h" for the cmd_foo() prototype
464 + definition,
465 +
466 + - the test helper programs in the "t/helper/" directory that include
467 + "t/helper/test-tool.h" for the cmd__foo() prototype definition,
468 +
469 + - the xdiff implementation in the "xdiff/" directory that includes
470 + "xdiff/xinclude.h" for the xdiff machinery internals,
471 +
472 + - the unit test programs in "t/unit-tests/" directory that include
473 + "t/unit-tests/test-lib.h" that gives them the unit-tests
474 + framework, and
475 +
476 + - the source files that implement reftable in the "reftable/"
477 + directory that include "reftable/system.h" for the reftable
478 + internals,
479 +
480 + are allowed to assume that they do not have to include
481 + <git-compat-util.h> themselves, as it is included as the first
482 + '#include' in these header files. These headers must be the first
483 + header file to be "#include"d in them, though.
484
485 - A C file must directly include the header files that declare the
486 functions and the types it uses, except for the functions and types