Commit | Line | Data |
---|---|---|
6d0618a8 JS |
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 | |
dfb047b9 NS |
24 | contributing to). It is always preferable to match the _local_ |
25 | convention. New code added to git suite is expected to match | |
26 | the overall style of existing code. Modifications to existing | |
27 | code is expected to match the style the surrounding code already | |
28 | uses (even if it doesn't match the overall style of existing code). | |
29 | ||
30 | But if you must have a list of rules, here they are. | |
6d0618a8 JS |
31 | |
32 | For shell scripts specifically (not exhaustive): | |
33 | ||
34 | - We prefer $( ... ) for command substitution; unlike ``, it | |
35 | properly nests. It should have been the way Bourne spelled | |
36 | it from day one, but unfortunately isn't. | |
37 | ||
38 | - We use ${parameter-word} and its [-=?+] siblings, and their | |
39 | colon'ed "unset or null" form. | |
40 | ||
41 | - We use ${parameter#word} and its [#%] siblings, and their | |
42 | doubled "longest matching" form. | |
43 | ||
44 | - We use Arithmetic Expansion $(( ... )). | |
45 | ||
46 | - No "Substring Expansion" ${parameter:offset:length}. | |
47 | ||
48 | - No shell arrays. | |
49 | ||
50 | - No strlen ${#parameter}. | |
51 | ||
52 | - No regexp ${parameter/pattern/string}. | |
53 | ||
54 | - We do not use Process Substitution <(list) or >(list). | |
55 | ||
56 | - We prefer "test" over "[ ... ]". | |
57 | ||
58 | - We do not write the noiseword "function" in front of shell | |
59 | functions. | |
60 | ||
009c98ee JH |
61 | - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, |
62 | [::], [==], nor [..]) for portability. | |
63 | ||
64 | - We do not use \{m,n\}; | |
65 | ||
66 | - We do not use -E; | |
67 | ||
68 | - We do not use ? nor + (which are \{0,1\} and \{1,\} | |
69 | respectively in BRE) but that goes without saying as these | |
70 | are ERE elements not BRE (note that \? and \+ are not even part | |
71 | of BRE -- making them accessible from BRE is a GNU extension). | |
72 | ||
6d0618a8 JS |
73 | For C programs: |
74 | ||
75 | - We use tabs to indent, and interpret tabs as taking up to | |
76 | 8 spaces. | |
77 | ||
78 | - We try to keep to at most 80 characters per line. | |
79 | ||
80 | - When declaring pointers, the star sides with the variable | |
81 | name, i.e. "char *string", not "char* string" or | |
82 | "char * string". This makes it easier to understand code | |
83 | like "char *string, c;". | |
84 | ||
85 | - We avoid using braces unnecessarily. I.e. | |
86 | ||
87 | if (bla) { | |
88 | x = 1; | |
89 | } | |
90 | ||
91 | is frowned upon. A gray area is when the statement extends | |
92 | over a few lines, and/or you have a lengthy comment atop of | |
93 | it. Also, like in the Linux kernel, if there is a long list | |
94 | of "else if" statements, it can make sense to add braces to | |
95 | single line blocks. | |
96 | ||
0b0b8cd7 MV |
97 | - We try to avoid assignments inside if(). |
98 | ||
6d0618a8 JS |
99 | - Try to make your code understandable. You may put comments |
100 | in, but comments invariably tend to stale out when the code | |
101 | they were describing changes. Often splitting a function | |
102 | into two makes the intention of the code much clearer. | |
103 | ||
104 | - Double negation is often harder to understand than no negation | |
105 | at all. | |
106 | ||
107 | - Some clever tricks, like using the !! operator with arithmetic | |
108 | constructs, can be extremely confusing to others. Avoid them, | |
109 | unless there is a compelling reason to use them. | |
110 | ||
111 | - Use the API. No, really. We have a strbuf (variable length | |
112 | string), several arrays with the ALLOC_GROW() macro, a | |
c455c87c | 113 | string_list for sorted string lists, a hash map (mapping struct |
6d0618a8 JS |
114 | objects) named "struct decorate", amongst other things. |
115 | ||
116 | - When you come up with an API, document it. | |
117 | ||
118 | - The first #include in C files, except in platform specific | |
119 | compat/ implementations, should be git-compat-util.h or another | |
120 | header file that includes it, such as cache.h or builtin.h. | |
121 | ||
122 | - If you are planning a new command, consider writing it in shell | |
123 | or perl first, so that changes in semantics can be easily | |
124 | changed and discussed. Many git commands started out like | |
125 | that, and a few are still scripts. | |
126 | ||
127 | - Avoid introducing a new dependency into git. This means you | |
128 | usually should stay away from scripting languages not already | |
129 | used in the git core command set (unless your command is clearly | |
130 | separate from it, such as an importer to convert random-scm-X | |
131 | repositories to git). | |
57199892 KB |
132 | |
133 | - When we pass <string, length> pair to functions, we should try to | |
134 | pass them in that order. |