]>
Commit | Line | Data |
---|---|---|
24aec6db | 1 | # Libgit2 Conventions |
7335ffc3 | 2 | |
24aec6db BS |
3 | We like to keep the source consistent and readable. Herein are some guidelines |
4 | that should help with that. | |
7335ffc3 | 5 | |
7335ffc3 | 6 | |
24aec6db | 7 | ## Naming Things |
7335ffc3 | 8 | |
24aec6db | 9 | All types and functions start with `git_`, and all #define macros start with `GIT_`. |
7335ffc3 | 10 | |
24aec6db BS |
11 | Functions with a single output parameter should name that parameter `out`. |
12 | Multiple outputs should be named `foo_out`, `bar_out`, etc. | |
7335ffc3 | 13 | |
24aec6db BS |
14 | Parameters of type `git_oid` should be named `id`, or `foo_id`. Calls that |
15 | return an OID should be named `git_foo_id`. | |
6533aadc | 16 | |
24aec6db BS |
17 | Where there is a callback passed in, the `void *` that is passed into it should |
18 | be named "payload". | |
6533aadc | 19 | |
24aec6db | 20 | ## Typedef |
7335ffc3 | 21 | |
24aec6db BS |
22 | Wherever possible, use `typedef`. If a structure is just a collection of |
23 | function pointers, the pointer types don't need to be separately typedef'd, but | |
24 | loose function pointer types should be. | |
7335ffc3 | 25 | |
24aec6db | 26 | ## Exports |
7335ffc3 SP |
27 | |
28 | All exported functions must be declared as: | |
29 | ||
ee72ffd0 | 30 | ```C |
24aec6db | 31 | GIT_EXTERN(result_type) git_modulename_functionname(arg_list); |
ee72ffd0 | 32 | ``` |
7335ffc3 | 33 | |
24aec6db | 34 | ## Internals |
7335ffc3 SP |
35 | |
36 | Functions whose modulename is followed by two underscores, | |
24aec6db | 37 | for example `git_odb__read_packed`, are semi-private functions. |
7335ffc3 SP |
38 | They are primarily intended for use within the library itself, |
39 | and may disappear or change their signature in a future release. | |
40 | ||
24aec6db BS |
41 | ## Parameters |
42 | ||
43 | Out parameters come first. | |
44 | ||
45 | Whenever possible, pass argument pointers as `const`. Some structures (such | |
46 | as `git_repository` and `git_index`) have internal structure that prevents | |
47 | this. | |
48 | ||
49 | Callbacks should always take a `void *` payload as their last parameter. | |
50 | Callback pointers are grouped with their payloads, and come last when passed as | |
51 | arguments: | |
52 | ||
53 | ```C | |
54 | int foo(git_repository *repo, git_foo_cb callback, void *payload); | |
55 | ``` | |
56 | ||
57 | ||
58 | ## Memory Ownership | |
59 | ||
60 | Some APIs allocate memory which the caller is responsible for freeing; others | |
61 | return a pointer into a buffer that's owned by some other object. Make this | |
62 | explicit in the documentation. | |
63 | ||
64 | ||
65 | ## Return codes | |
66 | ||
67 | Return an `int` when a public API can fail in multiple ways. These may be | |
68 | transformed into exception types in some bindings, so returning a semantically | |
69 | appropriate error code is important. Check | |
70 | [`errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h) | |
71 | for the return codes already defined. | |
72 | ||
73 | Use `giterr_set` to provide extended error information to callers. | |
7335ffc3 | 74 | |
24aec6db BS |
75 | If an error is not to be propagated, use `giterr_clear` to prevent callers from |
76 | getting the wrong error message later on. | |
7335ffc3 | 77 | |
7335ffc3 | 78 | |
24aec6db BS |
79 | ## Opaque Structs |
80 | ||
81 | Most types should be opaque, e.g.: | |
7335ffc3 | 82 | |
ee72ffd0 | 83 | ```C |
24aec6db | 84 | typedef struct git_odb git_odb; |
ee72ffd0 | 85 | ``` |
7335ffc3 | 86 | |
24aec6db BS |
87 | ...with allocation functions returning an "instance" created within |
88 | the library, and not within the application. This allows the type | |
89 | to grow (or shrink) in size without rebuilding client code. | |
90 | ||
91 | To preserve ABI compatibility, include an `int version` field in all opaque | |
92 | structures, and initialize to the latest version in the construction call. | |
93 | Increment the "latest" version whenever the structure changes, and try to only | |
94 | append to the end of the structure. | |
6dafd056 | 95 | |
24aec6db | 96 | ## Option Structures |
6dafd056 | 97 | |
24aec6db BS |
98 | If a function's parameter count is too high, it may be desirable to package up |
99 | the options in a structure. Make them transparent, include a version field, | |
100 | and provide an initializer constant or constructor. Using these structures | |
101 | should be this easy: | |
7335ffc3 | 102 | |
24aec6db BS |
103 | ```C |
104 | git_foo_options opts = GIT_FOO_OPTIONS_INIT; | |
105 | opts.baz = BAZ_OPTION_ONE; | |
106 | git_foo(&opts); | |
107 | ``` | |
0e7fa1fe | 108 | |
24aec6db | 109 | ## Enumerations |
0e7fa1fe | 110 | |
24aec6db BS |
111 | Typedef all enumerated types. If each option stands alone, use the enum type |
112 | for passing them as parameters; if they are flags, pass them as `unsigned int`. | |
7335ffc3 | 113 | |
24aec6db | 114 | ## Code Layout |
7335ffc3 | 115 | |
24aec6db BS |
116 | Try to keep lines less than 80 characters long. Use common sense to wrap most |
117 | code lines; public function declarations should use this convention: | |
7335ffc3 | 118 | |
ee72ffd0 | 119 | ```C |
24aec6db BS |
120 | GIT_EXTERN(int) git_foo_id( |
121 | git_oid **out, | |
122 | int a, | |
123 | int b); | |
124 | ``` | |
125 | ||
a541eafa | 126 | Indentation is done with tabs; set your editor's tab width to 3 for best effect. |
24aec6db | 127 | |
7335ffc3 | 128 | |
24aec6db | 129 | ## Documentation |
7335ffc3 | 130 | |
24aec6db BS |
131 | All comments should conform to Doxygen "javadoc" style conventions for |
132 | formatting the public API documentation. Try to document every parameter, and | |
133 | keep the comments up to date if you change the parameter list. | |
7335ffc3 | 134 | |
7335ffc3 | 135 | |
24aec6db BS |
136 | ## Public Header Template |
137 | ||
138 | Use this template when creating a new public header. | |
139 | ||
140 | ```C | |
141 | #ifndef INCLUDE_git_${filename}_h__ | |
142 | #define INCLUDE_git_${filename}_h__ | |
143 | ||
144 | #include "git/common.h" | |
145 | ||
146 | /** | |
147 | * @file git/${filename}.h | |
148 | * @brief Git some description | |
149 | * @defgroup git_${filename} some description routines | |
150 | * @ingroup Git | |
151 | * @{ | |
152 | */ | |
153 | GIT_BEGIN_DECL | |
154 | ||
155 | /* ... definitions ... */ | |
156 | ||
157 | /** @} */ | |
158 | GIT_END_DECL | |
159 | #endif | |
ee72ffd0 | 160 | ``` |
24aec6db | 161 | |
394711ff TN |
162 | ## Inlined functions |
163 | ||
164 | All inlined functions must be declared as: | |
165 | ||
166 | ```C | |
167 | GIT_INLINE(result_type) git_modulename_functionname(arg_list); | |
168 | ``` | |
169 |