Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 1 | Like other projects, we also have some guidelines to keep to the |
| 2 | code. For git in general, three rough rules are: |
| 3 | |
| 4 | - Most importantly, we never say "It's in POSIX; we'll happily |
| 5 | ignore your needs should your system not conform to it." |
| 6 | We live in the real world. |
| 7 | |
| 8 | - However, we often say "Let's stay away from that construct, |
| 9 | it's not even in POSIX". |
| 10 | |
| 11 | - In spite of the above two rules, we sometimes say "Although |
| 12 | this is not in POSIX, it (is so convenient | makes the code |
| 13 | much more readable | has other good characteristics) and |
| 14 | practically all the platforms we care about support it, so |
| 15 | let's use it". |
| 16 | |
| 17 | Again, we live in the real world, and it is sometimes a |
| 18 | judgement call, the decision based more on real world |
| 19 | constraints people face than what the paper standard says. |
| 20 | |
| 21 | |
| 22 | As for more concrete guidelines, just imitate the existing code |
| 23 | (this is a good guideline, no matter which project you are |
| 24 | contributing to). But if you must have a list of rules, |
| 25 | here they are. |
| 26 | |
| 27 | For shell scripts specifically (not exhaustive): |
| 28 | |
| 29 | - We prefer $( ... ) for command substitution; unlike ``, it |
| 30 | properly nests. It should have been the way Bourne spelled |
| 31 | it from day one, but unfortunately isn't. |
| 32 | |
| 33 | - We use ${parameter-word} and its [-=?+] siblings, and their |
| 34 | colon'ed "unset or null" form. |
| 35 | |
| 36 | - We use ${parameter#word} and its [#%] siblings, and their |
| 37 | doubled "longest matching" form. |
| 38 | |
| 39 | - We use Arithmetic Expansion $(( ... )). |
| 40 | |
| 41 | - No "Substring Expansion" ${parameter:offset:length}. |
| 42 | |
| 43 | - No shell arrays. |
| 44 | |
| 45 | - No strlen ${#parameter}. |
| 46 | |
| 47 | - No regexp ${parameter/pattern/string}. |
| 48 | |
| 49 | - We do not use Process Substitution <(list) or >(list). |
| 50 | |
| 51 | - We prefer "test" over "[ ... ]". |
| 52 | |
| 53 | - We do not write the noiseword "function" in front of shell |
| 54 | functions. |
| 55 | |
Junio C Hamano | 009c98e | 2008-03-01 18:18:16 -0800 | [diff] [blame] | 56 | - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, |
| 57 | [::], [==], nor [..]) for portability. |
| 58 | |
| 59 | - We do not use \{m,n\}; |
| 60 | |
| 61 | - We do not use -E; |
| 62 | |
| 63 | - We do not use ? nor + (which are \{0,1\} and \{1,\} |
| 64 | respectively in BRE) but that goes without saying as these |
| 65 | are ERE elements not BRE (note that \? and \+ are not even part |
| 66 | of BRE -- making them accessible from BRE is a GNU extension). |
| 67 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 68 | For C programs: |
| 69 | |
| 70 | - We use tabs to indent, and interpret tabs as taking up to |
| 71 | 8 spaces. |
| 72 | |
| 73 | - We try to keep to at most 80 characters per line. |
| 74 | |
| 75 | - When declaring pointers, the star sides with the variable |
| 76 | name, i.e. "char *string", not "char* string" or |
| 77 | "char * string". This makes it easier to understand code |
| 78 | like "char *string, c;". |
| 79 | |
| 80 | - We avoid using braces unnecessarily. I.e. |
| 81 | |
| 82 | if (bla) { |
| 83 | x = 1; |
| 84 | } |
| 85 | |
| 86 | is frowned upon. A gray area is when the statement extends |
| 87 | over a few lines, and/or you have a lengthy comment atop of |
| 88 | it. Also, like in the Linux kernel, if there is a long list |
| 89 | of "else if" statements, it can make sense to add braces to |
| 90 | single line blocks. |
| 91 | |
Miklos Vajna | 0b0b8cd | 2008-05-23 01:26:09 +0200 | [diff] [blame^] | 92 | - We try to avoid assignments inside if(). |
| 93 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 94 | - Try to make your code understandable. You may put comments |
| 95 | in, but comments invariably tend to stale out when the code |
| 96 | they were describing changes. Often splitting a function |
| 97 | into two makes the intention of the code much clearer. |
| 98 | |
| 99 | - Double negation is often harder to understand than no negation |
| 100 | at all. |
| 101 | |
| 102 | - Some clever tricks, like using the !! operator with arithmetic |
| 103 | constructs, can be extremely confusing to others. Avoid them, |
| 104 | unless there is a compelling reason to use them. |
| 105 | |
| 106 | - Use the API. No, really. We have a strbuf (variable length |
| 107 | string), several arrays with the ALLOC_GROW() macro, a |
| 108 | path_list for sorted string lists, a hash map (mapping struct |
| 109 | objects) named "struct decorate", amongst other things. |
| 110 | |
| 111 | - When you come up with an API, document it. |
| 112 | |
| 113 | - The first #include in C files, except in platform specific |
| 114 | compat/ implementations, should be git-compat-util.h or another |
| 115 | header file that includes it, such as cache.h or builtin.h. |
| 116 | |
| 117 | - If you are planning a new command, consider writing it in shell |
| 118 | or perl first, so that changes in semantics can be easily |
| 119 | changed and discussed. Many git commands started out like |
| 120 | that, and a few are still scripts. |
| 121 | |
| 122 | - Avoid introducing a new dependency into git. This means you |
| 123 | usually should stay away from scripting languages not already |
| 124 | used in the git core command set (unless your command is clearly |
| 125 | separate from it, such as an importer to convert random-scm-X |
| 126 | repositories to git). |