Git/Giving Back/Code guidelines
< Git
This page's first draft was adapted from an a commit publicized on the git newsgroup by Johannes Schindelin.[1]
Attitude
edit- Most importantly, we never say "It's in POSIX; we'll happily screw your system that does not conform." We live in the real world.
- However, we often say "Let's stay away from that construct, it's not even in POSIX".
- 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.
Shell scripts
editFor shell scripts specifically (not exhaustive):
- 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. - 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. - We use Arithmetic Expansion
$(( ... ))
. - No "Substring Expansion"
${parameter:offset:length}
. - No shell arrays.
- No strlen
${#parameter}
. - No regexp
${parameter/pattern/string}
. - We do not use Process Substitution
<(list)
or>(list)
. - We prefer "test" over "[ ... ]".
- We do not write noiseword
function
in front of shell functions.
C Programs
editFor C programs:
- Use tabs to indent, and interpret tabs as taking up to 8 spaces
- Try to keep to 80 characters per line
- 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 "char *string, c;"
- Do not use curly brackets 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. - 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.
- 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 path_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things.
#include
system headers in git-compat-util.h. Some headers on some systems show subtle breakages when you change the order, so it is best to keep them in one place.
Footnotes
edit- ^ See commit 622b80b for the precise contents.