]>
Commit | Line | Data |
---|---|---|
24aec6db | 1 | # Libgit2 Conventions |
7335ffc3 | 2 | |
1631147c RB |
3 | We like to keep the source consistent and readable. Herein are some |
4 | guidelines that should help with that. | |
7335ffc3 | 5 | |
1631147c RB |
6 | ## Compatibility |
7 | ||
8 | `libgit2` runs on many different platforms with many different compilers. | |
1631147c | 9 | |
68a19ca9 RB |
10 | The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C) |
11 | (a.k.a. C89) compatible. | |
12 | ||
13 | Internally, `libgit2` is written using a portable subset of C99 - in order | |
14 | to maximize compatibility (e.g. with MSVC) we avoid certain C99 | |
15 | extensions. Specifically, we keep local variable declarations at the tops | |
16 | of blocks only and we avoid `//` style comments. | |
17 | ||
18 | Also, to the greatest extent possible, we try to avoid lots of `#ifdef`s | |
19 | inside the core code base. This is somewhat unavoidable, but since it can | |
20 | really hamper maintainability, we keep it to a minimum. | |
1631147c RB |
21 | |
22 | ## Match Surrounding Code | |
23 | ||
24 | If there is one rule to take away from this document, it is *new code should | |
25 | match the surrounding code in a way that makes it impossible to distinguish | |
26 | the new from the old.* Consistency is more important to us than anyone's | |
27 | personal opinion about where braces should be placed or spaces vs. tabs. | |
28 | ||
29 | If a section of code is being completely rewritten, it is okay to bring it | |
30 | in line with the standards that are laid out here, but we will not accept | |
31 | submissions that contain a large number of changes that are merely | |
32 | reformatting. | |
7335ffc3 | 33 | |
24aec6db | 34 | ## Naming Things |
7335ffc3 | 35 | |
1631147c RB |
36 | All external types and functions start with `git_` and all `#define` macros |
37 | start with `GIT_`. The `libgit2` API is mostly broken into related | |
38 | functional modules each with a corresponding header. All functions in a | |
39 | module should be named like `git_modulename_functioname()` | |
40 | (e.g. `git_repository_open()`). | |
7335ffc3 | 41 | |
24aec6db BS |
42 | Functions with a single output parameter should name that parameter `out`. |
43 | Multiple outputs should be named `foo_out`, `bar_out`, etc. | |
7335ffc3 | 44 | |
24aec6db BS |
45 | Parameters of type `git_oid` should be named `id`, or `foo_id`. Calls that |
46 | return an OID should be named `git_foo_id`. | |
6533aadc | 47 | |
1631147c RB |
48 | Where a callback function is used, the function should also include a |
49 | user-supplied extra input that is a `void *` named "payload" that will be | |
50 | passed through to the callback at each invocation. | |
6533aadc | 51 | |
1631147c | 52 | ## Typedefs |
7335ffc3 | 53 | |
1631147c RB |
54 | Wherever possible, use `typedef`. In some cases, if a structure is just a |
55 | collection of function pointers, the pointer types don't need to be | |
56 | separately typedef'd, but loose function pointer types should be. | |
7335ffc3 | 57 | |
24aec6db | 58 | ## Exports |
7335ffc3 SP |
59 | |
60 | All exported functions must be declared as: | |
61 | ||
1631147c | 62 | ```c |
24aec6db | 63 | GIT_EXTERN(result_type) git_modulename_functionname(arg_list); |
ee72ffd0 | 64 | ``` |
7335ffc3 | 65 | |
24aec6db | 66 | ## Internals |
7335ffc3 | 67 | |
1631147c | 68 | Functions whose *modulename* is followed by two underscores, |
24aec6db | 69 | for example `git_odb__read_packed`, are semi-private functions. |
7335ffc3 SP |
70 | They are primarily intended for use within the library itself, |
71 | and may disappear or change their signature in a future release. | |
72 | ||
24aec6db BS |
73 | ## Parameters |
74 | ||
75 | Out parameters come first. | |
76 | ||
77 | Whenever possible, pass argument pointers as `const`. Some structures (such | |
1631147c RB |
78 | as `git_repository` and `git_index`) have mutable internal structure that |
79 | prevents this. | |
24aec6db BS |
80 | |
81 | Callbacks should always take a `void *` payload as their last parameter. | |
1631147c RB |
82 | Callback pointers are grouped with their payloads, and typically come last |
83 | when passed as arguments: | |
24aec6db | 84 | |
1631147c RB |
85 | ```c |
86 | int git_foo(git_repository *repo, git_foo_cb callback, void *payload); | |
24aec6db BS |
87 | ``` |
88 | ||
24aec6db BS |
89 | ## Memory Ownership |
90 | ||
91 | Some APIs allocate memory which the caller is responsible for freeing; others | |
92 | return a pointer into a buffer that's owned by some other object. Make this | |
93 | explicit in the documentation. | |
94 | ||
24aec6db BS |
95 | ## Return codes |
96 | ||
1631147c RB |
97 | Most public APIs should return an `int` error code. As is typical with most |
98 | C library functions, a zero value indicates success and a negative value | |
99 | indicates failure. | |
100 | ||
101 | Some bindings will transform these returned error codes into exception | |
102 | types, so returning a semantically appropriate error code is important. | |
103 | Check | |
104 | [`include/git2/errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h) | |
24aec6db BS |
105 | for the return codes already defined. |
106 | ||
1631147c RB |
107 | In your implementation, use `giterr_set()` to provide extended error |
108 | information to callers. | |
7335ffc3 | 109 | |
1631147c RB |
110 | If a `libgit2` function internally invokes another function that reports an |
111 | error, but the error is not propagated up, use `giterr_clear()` to prevent | |
112 | callers from getting the wrong error message later on. | |
7335ffc3 | 113 | |
7335ffc3 | 114 | |
1631147c | 115 | ## Structs |
24aec6db | 116 | |
1631147c | 117 | Most public types should be opaque, e.g.: |
7335ffc3 | 118 | |
ee72ffd0 | 119 | ```C |
24aec6db | 120 | typedef struct git_odb git_odb; |
ee72ffd0 | 121 | ``` |
7335ffc3 | 122 | |
24aec6db BS |
123 | ...with allocation functions returning an "instance" created within |
124 | the library, and not within the application. This allows the type | |
125 | to grow (or shrink) in size without rebuilding client code. | |
126 | ||
127 | To preserve ABI compatibility, include an `int version` field in all opaque | |
128 | structures, and initialize to the latest version in the construction call. | |
129 | Increment the "latest" version whenever the structure changes, and try to only | |
130 | append to the end of the structure. | |
6dafd056 | 131 | |
24aec6db | 132 | ## Option Structures |
6dafd056 | 133 | |
1631147c RB |
134 | If a function's parameter count is too high, it may be desirable to package |
135 | up the options in a structure. Make them transparent, include a version | |
136 | field, and provide an initializer constant or constructor. Using these | |
137 | structures should be this easy: | |
7335ffc3 | 138 | |
24aec6db BS |
139 | ```C |
140 | git_foo_options opts = GIT_FOO_OPTIONS_INIT; | |
141 | opts.baz = BAZ_OPTION_ONE; | |
142 | git_foo(&opts); | |
143 | ``` | |
0e7fa1fe | 144 | |
24aec6db | 145 | ## Enumerations |
0e7fa1fe | 146 | |
1631147c RB |
147 | Typedef all enumerated types. If each option stands alone, use the enum |
148 | type for passing them as parameters; if they are flags to be OR'ed together, | |
149 | pass them as `unsigned int` or `uint32_t` or some appropriate type. | |
7335ffc3 | 150 | |
24aec6db | 151 | ## Code Layout |
7335ffc3 | 152 | |
1631147c RB |
153 | Try to keep lines less than 80 characters long. This is a loose |
154 | requirement, but going significantly over 80 columns is not nice. | |
7335ffc3 | 155 | |
1631147c RB |
156 | Use common sense to wrap most code lines; public function declarations |
157 | can use a couple of different styles: | |
158 | ||
159 | ```c | |
160 | /** All on one line is okay if it fits */ | |
161 | GIT_EXTERN(int) git_foo_simple(git_oid *id); | |
162 | ||
163 | /** Otherwise one argument per line is a good next step */ | |
24aec6db | 164 | GIT_EXTERN(int) git_foo_id( |
1631147c RB |
165 | git_oid **out, |
166 | int a, | |
167 | int b); | |
24aec6db BS |
168 | ``` |
169 | ||
1631147c | 170 | Indent with tabs; set your editor's tab width to 4 for best effect. |
24aec6db | 171 | |
1631147c RB |
172 | Avoid trailing whitespace and only commit Unix-style newlines (i.e. no CRLF |
173 | in the repository - just set `core.autocrlf` to true if you are writing code | |
174 | on a Windows machine). | |
7335ffc3 | 175 | |
24aec6db | 176 | ## Documentation |
7335ffc3 | 177 | |
24aec6db | 178 | All comments should conform to Doxygen "javadoc" style conventions for |
1631147c RB |
179 | formatting the public API documentation. Try to document every parameter, |
180 | and keep the comments up to date if you change the parameter list. | |
7335ffc3 | 181 | |
24aec6db BS |
182 | ## Public Header Template |
183 | ||
184 | Use this template when creating a new public header. | |
185 | ||
186 | ```C | |
187 | #ifndef INCLUDE_git_${filename}_h__ | |
188 | #define INCLUDE_git_${filename}_h__ | |
189 | ||
190 | #include "git/common.h" | |
191 | ||
192 | /** | |
193 | * @file git/${filename}.h | |
194 | * @brief Git some description | |
195 | * @defgroup git_${filename} some description routines | |
196 | * @ingroup Git | |
197 | * @{ | |
198 | */ | |
199 | GIT_BEGIN_DECL | |
200 | ||
201 | /* ... definitions ... */ | |
202 | ||
203 | /** @} */ | |
204 | GIT_END_DECL | |
205 | #endif | |
ee72ffd0 | 206 | ``` |
24aec6db | 207 | |
394711ff TN |
208 | ## Inlined functions |
209 | ||
210 | All inlined functions must be declared as: | |
211 | ||
212 | ```C | |
213 | GIT_INLINE(result_type) git_modulename_functionname(arg_list); | |
214 | ``` | |
215 | ||
68a19ca9 RB |
216 | `GIT_INLINE` (or `inline`) should not be used in public headers in order |
217 | to preserve ANSI C compatibility. | |
218 | ||
1631147c RB |
219 | ## Tests |
220 | ||
a313de0d | 221 | `libgit2` uses the [clar](https://github.com/vmg/clar) testing framework. |
1631147c RB |
222 | |
223 | All PRs should have corresponding tests. | |
224 | ||
225 | * If the PR fixes an existing issue, the test should fail prior to applying | |
226 | the PR and succeed after applying it. | |
227 | * If the PR is for new functionality, then the tests should exercise that | |
228 | new functionality to a certain extent. We don't require 100% coverage | |
229 | right now (although we are getting stricter over time). | |
230 | ||
231 | When adding new tests, we prefer if you attempt to reuse existing test data | |
232 | (in `tests-clar/resources/`) if possible. If you are going to add new test | |
233 | repositories, please try to strip them of unnecessary files (e.g. sample | |
234 | hooks, etc). |