diff options
Diffstat (limited to 'Documentation/CodingGuidelines')
| -rw-r--r-- | Documentation/CodingGuidelines | 82 |
1 files changed, 69 insertions, 13 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 48aa4edfbd..227f46ae40 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -75,7 +75,7 @@ For shell scripts specifically (not exhaustive): - If you want to find out if a command is available on the user's $PATH, you should use 'type <command>', instead of 'which <command>'. - The output of 'which' is not machine parseable and its exit code + The output of 'which' is not machine parsable and its exit code is not reliable across platforms. - We use POSIX compliant parameter substitutions and avoid bashisms; @@ -91,16 +91,10 @@ For shell scripts specifically (not exhaustive): - No shell arrays. - - No strlen ${#parameter}. - - No pattern replacement ${parameter/pattern/string}. - We use Arithmetic Expansion $(( ... )). - - Inside Arithmetic Expansion, spell shell variables with $ in front - of them, as some shells do not grok $((x)) while accepting $(($x)) - just fine (e.g. dash older than 0.5.4). - - We do not use Process Substitution <(list) or >(list). - Do not write control structures on a single line with semicolon. @@ -118,6 +112,24 @@ For shell scripts specifically (not exhaustive): do this fi + - If a command sequence joined with && or || or | spans multiple + lines, put each command on a separate line and put && and || and | + operators at the end of each line, rather than the start. This + means you don't need to use \ to join lines, since the above + operators imply the sequence isn't finished. + + (incorrect) + grep blob verify_pack_result \ + | awk -f print_1.awk \ + | sort >actual && + ... + + (correct) + grep blob verify_pack_result | + awk -f print_1.awk | + sort >actual && + ... + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell @@ -177,10 +189,30 @@ 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. That means that you should not use C99 - initializers, even if a lot of compilers grok it. + including old ones. You should not use features from newer C + standard, even if your compiler groks them. + + There are a few exceptions to this guideline: + + . since early 2012 with e1327023ea, we have been using an enum + definition whose last element is followed by a comma. This, like + an array initializer that ends with a trailing comma, can be used + to reduce the patch noise when adding a new identifier at the end. + + . since mid 2017 with cbc0f81d, we have been using designated + initializers for struct (e.g. "struct t v = { .val = 'a' };"). - - Variables have to be declared at the beginning of the block. + . since mid 2017 with 512f41cf, we have been using designated + initializers for array (e.g. "int array[10] = { [5] = 2 }"). + + These used to be forbidden, but we have not heard any breakage + report, and they are assumed to be safe. + + - 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. - NULL pointers shall be written as NULL, not as 0. @@ -200,6 +232,18 @@ For C programs: while( condition ) func (bar+1); + - Do not explicitly compare an integral value with constant 0 or '\0', + or a pointer value with constant NULL. For instance, to validate that + counted array <ptr, cnt> is initialized but has no elements, write: + + if (!ptr || cnt) + BUG("empty array expected"); + + and not: + + if (ptr == NULL || cnt != 0); + BUG("empty array expected"); + - We avoid using braces unnecessarily. I.e. if (bla) { @@ -358,7 +402,10 @@ For C programs: string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - - When you come up with an API, document it. + - When you come up with an API, document its functions and structures + in the header file that exposes the API to its callers. Use what is + in "strbuf.h" as a model for the appropriate tone and level of + detail. - The first #include in C files, except in platform specific compat/ implementations, must be either "git-compat-util.h", "cache.h" or @@ -391,6 +438,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + For Perl programs: - Most of the C guidelines above apply. @@ -559,11 +612,14 @@ Writing Documentation: or commands: Literal examples (e.g. use of command-line options, command names, - branch names, configuration and environment variables) must be - typeset in monospace (i.e. wrapped with backticks): + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset in monospace (i.e. wrapped with + backticks): `--pretty=oneline` `git rev-list` `remote.pushDefault` + `http://git.example.com` + `.git/config` `GIT_DIR` `HEAD` |