CONVENTIONS.md

   1 # Libgit2 Conventions
   2
   3 We like to keep the source consistent and readable.  Herein are some
   4 guidelines that should help with that.
   5
   6 ## Compatibility
   7
   8 `libgit2` runs on many different platforms with many different compilers.
   9
  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.
  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.
  33
  34 ## Naming Things
  35
  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()`).
  41
  42 Functions with a single output parameter should name that parameter `out`.
  43 Multiple outputs should be named `foo_out`, `bar_out`, etc.
  44
  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`.
  47
  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.
  51
  52 ## Typedefs
  53
  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.
  57
  58 ## Exports
  59
  60 All exported functions must be declared as:
  61
  62 ```c
  63 GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
  64 ```
  65
  66 ## Internals
  67
  68 Functions whose *modulename* is followed by two underscores,
  69 for example `git_odb__read_packed`, are semi-private functions.
  70 They are primarily intended for use within the library itself,
  71 and may disappear or change their signature in a future release.
  72
  73 ## Parameters
  74
  75 Out parameters come first.
  76
  77 Whenever possible, pass argument pointers as `const`.  Some structures (such
  78 as `git_repository` and `git_index`) have mutable internal structure that
  79 prevents this.
  80
  81 Callbacks should always take a `void *` payload as their last parameter.
  82 Callback pointers are grouped with their payloads, and typically come last
  83 when passed as arguments:
  84
  85 ```c
  86 int git_foo(git_repository *repo, git_foo_cb callback, void *payload);
  87 ```
  88
  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
  95 ## Return codes
  96
  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)
 105 for the return codes already defined.
 106
 107 In your implementation, use `giterr_set()` to provide extended error
 108 information to callers.
 109
 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.
 113
 114
 115 ## Structs
 116
 117 Most public types should be opaque, e.g.:
 118
 119 ```C
 120 typedef struct git_odb git_odb;
 121 ```
 122
 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.
 131
 132 ## Option Structures
 133
 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:
 138
 139 ```C
 140 git_foo_options opts = GIT_FOO_OPTIONS_INIT;
 141 opts.baz = BAZ_OPTION_ONE;
 142 git_foo(&opts);
 143 ```
 144
 145 ## Enumerations
 146
 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.
 150
 151 ## Code Layout
 152
 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.
 155
 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 */
 164 GIT_EXTERN(int) git_foo_id(
 165         git_oid **out,
 166         int a,
 167         int b);
 168 ```
 169
 170 Indent with tabs; set your editor's tab width to 4 for best effect.
 171
 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).
 175
 176 ## Documentation
 177
 178 All comments should conform to Doxygen "javadoc" style conventions for
 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.
 181
 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
 206 ```
 207
 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
 216 `GIT_INLINE` (or `inline`) should not be used in public headers in order
 217 to preserve ANSI C compatibility.
 218
 219 ## Tests
 220
 221 `libgit2` uses the [clar](https://github.com/vmg/clar) testing framework.
 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).