Git/Giving Back/Code guidelines

From Wikibooks, open books for an open world
< Git
Jump to: navigation, search

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[edit]

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.

C Programs[edit]

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.

Footnotes[edit]

  1. ^ See commit 622b80b for the precise contents.