mirror of
https://github.com/git/git
synced 2024-08-29 12:39:18 +00:00
![brian m. carlson](/assets/img/avatar_default.png)
The style for multi-line comments is often mentioned and should be documented for clarity. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
315 lines
11 KiB
Plaintext
315 lines
11 KiB
Plaintext
Like other projects, we also have some guidelines to keep to the
|
|
code. For Git in general, three 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."
|
|
We live in the real world.
|
|
|
|
- However, we often say "Let's stay away from that construct,
|
|
it's not even in POSIX".
|
|
|
|
- In spite of the above two rules, we sometimes say "Although
|
|
this is not in POSIX, it (is so convenient | makes the code
|
|
much more readable | has other good characteristics) and
|
|
practically all the platforms we care about support it, so
|
|
let's use it".
|
|
|
|
Again, we live in the real world, and it is sometimes a
|
|
judgement call, the decision based more on real world
|
|
constraints people face than what the paper standard says.
|
|
|
|
Make your code readable and sensible, and don't try to be clever.
|
|
|
|
As for more concrete guidelines, just imitate the existing code
|
|
(this is a good guideline, no matter which project you are
|
|
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
|
|
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.
|
|
|
|
For shell scripts specifically (not exhaustive):
|
|
|
|
- We use tabs for indentation.
|
|
|
|
- Case arms are indented at the same depth as case and esac lines.
|
|
|
|
- Redirection operators should be written with space before, but no
|
|
space after them. In other words, write 'echo test >"$file"'
|
|
instead of 'echo test> $file' or 'echo test > $file'. Note that
|
|
even though it is not required by POSIX to double-quote the
|
|
redirection target in a variable (as shown above), our code does so
|
|
because some versions of bash issue a warning without the quotes.
|
|
|
|
- We prefer $( ... ) for command substitution; unlike ``, it
|
|
properly nests. It should have been the way Bourne spelled
|
|
it from day one, but unfortunately isn't.
|
|
|
|
- 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
|
|
is not reliable across platforms.
|
|
|
|
- We use POSIX compliant parameter substitutions and avoid bashisms;
|
|
namely:
|
|
|
|
- We use ${parameter-word} and its [-=?+] siblings, and their
|
|
colon'ed "unset or null" form.
|
|
|
|
- We use ${parameter#word} and its [#%] siblings, and their
|
|
doubled "longest matching" form.
|
|
|
|
- No "Substring Expansion" ${parameter:offset:length}.
|
|
|
|
- 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.
|
|
"then" should be on the next line for if statements, and "do"
|
|
should be on the next line for "while" and "for".
|
|
|
|
- We prefer "test" over "[ ... ]".
|
|
|
|
- We do not write the noiseword "function" in front of shell
|
|
functions.
|
|
|
|
- We prefer a space between the function name and the parentheses. The
|
|
opening "{" should also be on the same line.
|
|
E.g.: my_function () {
|
|
|
|
- As to use of grep, stick to a subset of BRE (namely, no \{m,n\},
|
|
[::], [==], nor [..]) for portability.
|
|
|
|
- We do not use \{m,n\};
|
|
|
|
- We do not use -E;
|
|
|
|
- We do not use ? nor + (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
|
|
of BRE -- making them accessible from BRE is a GNU extension).
|
|
|
|
- Use Git's gettext wrappers in git-sh-i18n to make the user
|
|
interface translatable. See "Marking strings for translation" in
|
|
po/README.
|
|
|
|
For C programs:
|
|
|
|
- We use tabs to indent, and interpret tabs as taking up to
|
|
8 spaces.
|
|
|
|
- We try to keep to at most 80 characters per line.
|
|
|
|
- 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.
|
|
|
|
- Variables have to be declared at the beginning of the block.
|
|
|
|
- NULL pointers shall be written as NULL, not as 0.
|
|
|
|
- When declaring pointers, the star sides with the variable
|
|
name, i.e. "char *string", not "char* string" or
|
|
"char * string". This makes it easier to understand code
|
|
like "char *string, c;".
|
|
|
|
- We avoid using braces unnecessarily. I.e.
|
|
|
|
if (bla) {
|
|
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().
|
|
|
|
- Try to make your code understandable. You may put comments
|
|
in, but comments invariably tend to stale out when the code
|
|
they were describing changes. Often splitting a function
|
|
into two makes the intention of the code much clearer.
|
|
|
|
- Multi-line comments include their delimiters on separate lines from
|
|
the text. E.g.
|
|
|
|
/*
|
|
* A very long
|
|
* multi-line comment.
|
|
*/
|
|
|
|
- Double negation is often harder to understand than no negation
|
|
at all.
|
|
|
|
- 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.
|
|
|
|
- Use the API. No, really. We have a strbuf (variable length
|
|
string), several arrays with the ALLOC_GROW() macro, a
|
|
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.
|
|
|
|
- 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.
|
|
|
|
- If you are planning a new command, consider writing it in shell
|
|
or perl first, so that changes in semantics can be easily
|
|
changed and discussed. Many Git commands started out like
|
|
that, and a few are still scripts.
|
|
|
|
- Avoid introducing a new dependency into Git. This means you
|
|
usually should stay away from scripting languages not already
|
|
used in the Git core command set (unless your command is clearly
|
|
separate from it, such as an importer to convert random-scm-X
|
|
repositories to Git).
|
|
|
|
- When we pass <string, length> pair to functions, we should try to
|
|
pass them in that order.
|
|
|
|
- Use Git's gettext wrappers to make the user interface
|
|
translatable. See "Marking strings for translation" in po/README.
|
|
|
|
For Perl programs:
|
|
|
|
- Most of the C guidelines above apply.
|
|
|
|
- We try to support Perl 5.8 and later ("use Perl 5.008").
|
|
|
|
- use strict and use warnings are strongly preferred.
|
|
|
|
- Don't overuse statement modifiers unless using them makes the
|
|
result easier to follow.
|
|
|
|
... do something ...
|
|
do_this() unless (condition);
|
|
... do something else ...
|
|
|
|
is more readable than:
|
|
|
|
... do something ...
|
|
unless (condition) {
|
|
do_this();
|
|
}
|
|
... do something else ...
|
|
|
|
*only* when the condition is so rare that do_this() will be almost
|
|
always called.
|
|
|
|
- We try to avoid assignments inside "if ()" conditions.
|
|
|
|
- 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/).
|
|
|
|
- As a minimum, we aim to be compatible with Python 2.6 and 2.7.
|
|
|
|
- Where required libraries do not restrict us to Python 2, we try to
|
|
also be compatible with Python 3.1 and later.
|
|
|
|
- When you must differentiate between Unicode literals and byte string
|
|
literals, it is OK to use the 'b' prefix. Even though the Python
|
|
documentation for version 2.6 does not mention this prefix, it has
|
|
been supported since version 2.6.0.
|
|
|
|
Writing Documentation:
|
|
|
|
Most (if not all) of the documentation pages are written in the
|
|
AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
|
|
processed into HTML and manpages (e.g. git.html and git.1 in the
|
|
same directory).
|
|
|
|
The documentation liberally mixes US and UK English (en_US/UK)
|
|
norms for spelling and grammar, which is somewhat unfortunate.
|
|
In an ideal world, it would have been better if it consistently
|
|
used only one and not the other, and we would have picked en_US
|
|
(if you wish to correct the English of some of the existing
|
|
documentation, please see the documentation-related advice in the
|
|
Documentation/SubmittingPatches file).
|
|
|
|
Every user-visible change should be reflected in the documentation.
|
|
The same general rule as for code applies -- imitate the existing
|
|
conventions. A few commented examples follow to provide reference
|
|
when writing or modifying command usage strings and synopsis sections
|
|
in the manual pages:
|
|
|
|
Placeholders are spelled in lowercase and enclosed in angle brackets:
|
|
<file>
|
|
--sort=<key>
|
|
--abbrev[=<n>]
|
|
|
|
Possibility of multiple occurrences is indicated by three dots:
|
|
<file>...
|
|
(One or more of <file>.)
|
|
|
|
Optional parts are enclosed in square brackets:
|
|
[<extra>]
|
|
(Zero or one <extra>.)
|
|
|
|
--exec-path[=<path>]
|
|
(Option with an optional argument. Note that the "=" is inside the
|
|
brackets.)
|
|
|
|
[<patch>...]
|
|
(Zero or more of <patch>. Note that the dots are inside, not
|
|
outside the brackets.)
|
|
|
|
Multiple alternatives are indicated with vertical bar:
|
|
[-q | --quiet]
|
|
[--utf8 | --no-utf8]
|
|
|
|
Parentheses are used for grouping:
|
|
[(<rev>|<range>)...]
|
|
(Any number of either <rev> or <range>. Parens are needed to make
|
|
it clear that "..." pertains to both <rev> and <range>.)
|
|
|
|
[(-p <parent>)...]
|
|
(Any number of option -p, each with one <parent> argument.)
|
|
|
|
git remote set-head <name> (-a | -d | <branch>)
|
|
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
|
|
brackets) be provided.)
|
|
|
|
And a somewhat more contrived example:
|
|
--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
|
|
Here "=" is outside the brackets, because "--diff-filter=" is a
|
|
valid usage. "*" has its own pair of brackets, because it can
|
|
(optionally) be specified only when one or more of the letters is
|
|
also provided.
|
|
|
|
A note on notation:
|
|
Use 'git' (all lowercase) when talking about commands i.e. something
|
|
the user would type into a shell and use 'Git' (uppercase first letter)
|
|
when talking about the version control system and its properties.
|