Like other projects, we also have some guidelines to keep to the
-code. For Git in general, three rough rules are:
+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."
"Once it _is_ in the tree, it's not really worth the patch noise to
go and fix it up."
- Cf. http://article.gmane.org/gmane.linux.kernel/943020
+ Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html
Make your code readable and sensible, and don't try to be clever.
interface translatable. See "Marking strings for translation" in
po/README.
+ - We do not write our "test" command with "-a" and "-o" and use "&&"
+ or "||" to concatenate multiple "test" commands instead, because
+ the use of "-a/-o" is often error-prone. E.g.
+
+ test -n "$x" -a "$a" = "$b"
+
+ is buggy and breaks when $x is "=", but
+
+ test -n "$x" && test "$a" = "$b"
+
+ does not have such a problem.
+
+
For C programs:
- We use tabs to indent, and interpret tabs as taking up to
- We try to keep to at most 80 characters per line.
+ - As a Git developer we assume you have a reasonably modern compiler
+ and we recommend you to enable the DEVELOPER makefile knob to
+ ensure your patch is clear of all compiler warnings we care about,
+ 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.
x = 1;
}
- is frowned upon. A gray area is when the statement extends
- over a few lines, and/or you have a lengthy comment atop of
- it. Also, like in the Linux kernel, if there is a long list
- of "else if" statements, it can make sense to add braces to
- single line blocks.
-
- - We try to avoid assignments inside if().
+ is frowned upon. But there are a few exceptions:
+
+ - When the statement extends over a few lines (e.g., a while loop
+ with an embedded conditional, or a comment). E.g.:
+
+ while (foo) {
+ if (x)
+ one();
+ else
+ two();
+ }
+
+ if (foo) {
+ /*
+ * This one requires some explanation,
+ * so we're better off with braces to make
+ * it obvious that the indentation is correct.
+ */
+ doit();
+ }
+
+ - When there are multiple arms to a conditional and some of them
+ require braces, enclose even a single line block in braces for
+ consistency. E.g.:
+
+ if (foo) {
+ doit();
+ } else {
+ one();
+ two();
+ three();
+ }
+
+ - We try to avoid assignments in the condition of an "if" statement.
- Try to make your code understandable. You may put comments
in, but comments invariably tend to stale out when the code
Note however that a comment that explains a translatable string to
translators uses a convention of starting with a magic token
- "TRANSLATORS: " immediately after the opening delimiter, even when
- it spans multiple lines. We do not add an asterisk at the beginning
- of each line, either. E.g.
+ "TRANSLATORS: ", e.g.
- /* TRANSLATORS: here is a comment that explains the string
- to be translated, that follows immediately after it */
+ /*
+ * TRANSLATORS: here is a comment that explains the string to
+ * be translated, that follows immediately after it.
+ */
_("Here is a translatable string explained by the above.");
- Double negation is often harder to understand than no negation
at all.
+ - There are two schools of thought when it comes to comparison,
+ especially inside a loop. Some people prefer to have the less stable
+ value on the left hand side and the more stable value on the right hand
+ side, e.g. if you have a loop that counts variable i down to the
+ lower bound,
+
+ while (i > lower_bound) {
+ do something;
+ i--;
+ }
+
+ Other people prefer to have the textual order of values match the
+ actual order of values in their comparison, so that they can
+ mentally draw a number line from left to right and place these
+ values in order, i.e.
+
+ while (lower_bound < i) {
+ do something;
+ i--;
+ }
+
+ Both are valid, and we use both. However, the more "stable" the
+ stable side becomes, the more we tend to prefer the former
+ (comparison with a constant, "i > 0", is an extreme example).
+ Just do not mix styles in the same part of the code and mimic
+ existing styles in the neighbourhood.
+
+ - There are two schools of thought when it comes to splitting a long
+ logical line into multiple lines. Some people push the second and
+ subsequent lines far enough to the right with tabs and align them:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of ||
+ the_source_text) {
+ ...
+
+ while other people prefer to align the second and the subsequent
+ lines with the column immediately inside the opening parenthesis,
+ with tabs and spaces, following our "tabstop is always a multiple
+ of 8" convention:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of ||
+ the_source_text) {
+ ...
+
+ Both are valid, and we use both. Again, just do not mix styles in
+ the same part of the code and mimic existing styles in the
+ neighbourhood.
+
+ - When splitting a long logical line, some people change line before
+ a binary operator, so that the result looks like a parse tree when
+ you turn your head 90-degrees counterclockwise:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to
+ || span_more_than_a_single_line_of_the_source_text) {
+
+ while other people prefer to leave the operator at the end of the
+ line:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of_the_source_text) {
+
+ Both are valid, but we tend to use the latter more, unless the
+ expression gets fairly complex, in which case the former tends to
+ be easier to read. Again, just do not mix styles in the same part
+ of the code and mimic existing styles in the neighbourhood.
+
+ - When splitting a long logical line, with everything else being
+ equal, it is preferable to split after the operator at higher
+ level in the parse tree. That is, this is more preferable:
+
+ if (a_very_long_variable * that_is_used_in +
+ a_very_long_expression) {
+ ...
+
+ than
+
+ if (a_very_long_variable *
+ that_is_used_in + a_very_long_expression) {
+ ...
+
- Some clever tricks, like using the !! operator with arithmetic
constructs, can be extremely confusing to others. Avoid them,
unless there is a compelling reason to use them.
- 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
- Use Git's gettext wrappers to make the user interface
translatable. See "Marking strings for translation" in po/README.
+ - Variables and functions local to a given source file should be marked
+ with "static". Variables that are visible to other source files
+ must be declared with "extern" in header files. However, function
+ declarations should not use "extern", as that is already the default.
+
For Perl programs:
- Most of the C guidelines above apply.
documentation for version 2.6 does not mention this prefix, it has
been supported since version 2.6.0.
+Error Messages
+
+ - Do not end error messages with a full stop.
+
+ - Do not capitalize ("unable to open %s", not "Unable to open %s")
+
+ - Say what the error is first ("cannot open %s", not "%s: cannot open")
+
+
+Externally Visible Names
+
+ - For configuration variable names, follow the existing convention:
+
+ . The section name indicates the affected subsystem.
+
+ . The subsection name, if any, indicates which of an unbounded set
+ of things to set the value for.
+
+ . 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. `-`),
+ and are broken using bumpyCaps in documentation as a hint to the
+ reader.
+
+ When choosing the variable namespace, do not use variable name for
+ specifying possibly unbounded set of things, most notably anything
+ an end user can freely come up with (e.g. branch names). Instead,
+ use subsection names or variable values, like the existing variable
+ branch.<name>.description does.
+
+
Writing Documentation:
Most (if not all) of the documentation pages are written in the
--sort=<key>
--abbrev[=<n>]
+ If a placeholder has multiple words, they are separated by dashes:
+ <new-branch-name>
+ --template=<template-directory>
+
Possibility of multiple occurrences is indicated by three dots:
<file>...
(One or more of <file>.)
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
- Multiple alternatives are indicated with vertical bar:
+ Multiple alternatives are indicated with vertical bars:
[-q | --quiet]
[--utf8 | --no-utf8]
Parentheses are used for grouping:
- [(<rev>|<range>)...]
+ [(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
modifying paragraphs or option/command explanations that contain options
or commands:
- Literal examples (e.g. use of command-line options, command names, and
- configuration variables) are typeset in monospace, and if you can use
- `backticks around word phrases`, do so.
+ 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):
`--pretty=oneline`
`git rev-list`
- `remote.pushdefault`
+ `remote.pushDefault`
+ `GIT_DIR`
+ `HEAD`
+
+ An environment variable must be prefixed with "$" only when referring to its
+ value and not when referring to the variable itself, in this case there is
+ nothing to add except the backticks:
+ `GIT_DIR` is specified
+ `$GIT_DIR/hooks/pre-receive`
Word phrases enclosed in `backtick characters` are rendered literally
and will not be further expanded. The use of `backticks` to achieve the