diff options
Diffstat (limited to 'Documentation/CodingGuidelines')
| -rw-r--r-- | Documentation/CodingGuidelines | 28 |
1 files changed, 18 insertions, 10 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 9d5c27807a..578587a471 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -1,5 +1,5 @@ -Like other projects, we also have some guidelines to keep to the -code. For Git in general, a few rough rules are: +Like other projects, we also have some guidelines for our code. For +Git in general, a few rough rules are: - Most importantly, we never say "It's in POSIX; we'll happily ignore your needs should your system not conform to it." @@ -24,7 +24,7 @@ code. For Git in general, a few rough rules are: "Once it _is_ in the tree, it's not really worth the patch noise to go and fix it up." - Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + Cf. https://lore.kernel.org/all/20100126160632.3bdbe172.akpm@linux-foundation.org/ - Log messages to explain your changes are as important as the changes themselves. Clearly written code and in-code comments @@ -40,7 +40,7 @@ As for more concrete guidelines, just imitate the existing code contributing to). It is always preferable to match the _local_ convention. New code added to Git suite is expected to match the overall style of existing code. Modifications to existing -code is expected to match the style the surrounding code already +code are 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 are some language @@ -188,6 +188,10 @@ For shell scripts specifically (not exhaustive): hopefully nobody starts using "local" before they are reimplemented in C ;-) + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. + "\xc2\xa2") in printf format strings, since hexadecimal escape + sequences are not portable. + For C programs: @@ -442,8 +446,12 @@ For C programs: detail. - 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. + implementations and sha1dc/, must be either "git-compat-util.h" or + one of the approved headers that includes it first for you. (The + approved headers currently include "builtin.h", + "t/helper/test-tool.h", "xdiff/xinclude.h", or + "reftable/system.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 @@ -482,7 +490,7 @@ For Perl programs: - Most of the C guidelines above apply. - - We try to support Perl 5.8 and later ("use Perl 5.008"). + - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). - use strict and use warnings are strongly preferred. @@ -510,7 +518,7 @@ For Perl programs: For Python scripts: - - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). + - We follow PEP-8 (https://peps.python.org/pep-0008/). - As a minimum, we aim to be compatible with Python 2.7. @@ -570,7 +578,7 @@ Externally Visible Names . The variable name describes the effect of tweaking this knob. The section and variable names that consist of multiple words are - formed by concatenating the words without punctuations (e.g. `-`), + formed by concatenating the words without punctuation marks (e.g. `-`), and are broken using bumpyCaps in documentation as a hint to the reader. @@ -683,7 +691,7 @@ Writing Documentation: Do: [-q | --quiet] Don't: [-q|--quiet] - Don't use spacing around "|" tokens when they're used to seperate the + Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: Do: --track[=(direct|inherit)] Don't: --track[=(direct | inherit)] |