Git/Giving Back/Code guidelines

This page's first draft was adapted from an a commit publicized on the git newsgroup by Johannes Schindelin.^[1]

Attitude

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.

For 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.

For 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.