diff options
Diffstat (limited to 'Documentation/CodingGuidelines')
| -rw-r--r-- | Documentation/CodingGuidelines | 69 |
1 files changed, 42 insertions, 27 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b20b2f94f1..9d5c27807a 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive): @@ -159,8 +162,6 @@ For shell scripts specifically (not exhaustive): - We do not use \{m,n\}; - - We do not use -E; - - We do not use ? or + (which are \{0,1\} and \{1,\} respectively in BRE) but that goes without saying as these are ERE elements not BRE (note that \? and \+ are not even part @@ -201,10 +202,19 @@ For C programs: by e.g. "echo DEVELOPER=1 >>config.mak". - We try to support a wide range of C compilers to compile Git with, - including old ones. You should not use features from newer C + including old ones. As of Git v2.35.0 Git requires C99 (we check + "__STDC_VERSION__"). You should not use features from a newer C standard, even if your compiler groks them. - There are a few exceptions to this guideline: + New C99 features have been phased in gradually, if something's new + in C99 but not used yet don't assume that it's safe to use, some + compilers we target have only partial support for it. These are + considered safe to use: + + . since around 2007 with 2b6854c863a, we have been using + initializer elements which are not computable at load time. E.g.: + + const char *args[] = {"constant", variable, NULL}; . since early 2012 with e1327023ea, we have been using an enum definition whose last element is followed by a comma. This, like @@ -220,18 +230,24 @@ For C programs: . since early 2021 with 765dc168882, we have been using variadic macros, mostly for printf-like trace and debug macros. - These used to be forbidden, but we have not heard any breakage - report, and they are assumed to be safe. + . since late 2021 with 44ba10d6, we have had variables declared in + the for loop "for (int i = 0; i < 10; i++)". + + New C99 features that we cannot use yet: + + . %z and %zu as a printf() argument for a size_t (the %z being for + the POSIX-specific ssize_t). Instead you should use + printf("%"PRIuMAX, (uintmax_t)v). These days the MSVC version we + rely on supports %z, but the C library used by MinGW does not. + + . Shorthand like ".a.b = *c" in struct initializations is known to + trip up an older IBM XLC version, use ".a = { .b = *c }" instead. + See the 33665d98 (reftable: make assignments portable to AIX xlc + v12.01, 2022-03-28). - Variables have to be declared at the beginning of the block, before the first statement (i.e. -Wdeclaration-after-statement). - - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)" - is still not allowed in this codebase. We are in the process of - allowing it by waiting to see that 44ba10d6 (revision: use C99 - declaration of variable in for() loop, 2021-11-14) does not get - complaints. Let's revisit this around November 2022. - - NULL pointers shall be written as NULL, not as 0. - When declaring pointers, the star sides with the variable @@ -492,17 +508,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). @@ -614,7 +619,7 @@ Writing Documentation: avoidance of gendered pronouns. - When it becomes awkward to stick to this style, prefer "you" when - addressing the the hypothetical user, and possibly "we" when + addressing the hypothetical user, and possibly "we" when discussing how the program might react to the user. E.g. You can use this option instead of --xyz, but we might remove @@ -658,8 +663,8 @@ Writing Documentation: (One or more of <file>.) Optional parts are enclosed in square brackets: - [<extra>] - (Zero or one <extra>.) + [<file>...] + (Zero or more of <file>.) --exec-path[=<path>] (Option with an optional argument. Note that the "=" is inside the @@ -673,6 +678,16 @@ Writing Documentation: [-q | --quiet] [--utf8 | --no-utf8] + Use spacing around "|" token(s), but not immediately after opening or + before closing a [] or () pair: + Do: [-q | --quiet] + Don't: [-q|--quiet] + + Don't use spacing around "|" tokens when they're used to seperate the + alternate arguments of an option: + Do: --track[=(direct|inherit)] + Don't: --track[=(direct | inherit)] + Parentheses are used for grouping: [(<rev> | <range>)...] (Any number of either <rev> or <range>. Parens are needed to make |