conventions.md 8.92 KB
Newer Older
1
# Libgit2 Conventions
2

3 4
We like to keep the source consistent and readable.  Herein are some
guidelines that should help with that.
5

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
## External API

We have a few rules to avoid surprising ways of calling functions and
some rules for consumers of the library to avoid stepping on each
other's toes.

 - Property accessors return the value directly (e.g. an `int` or
   `const char *`) but if a function can fail, we return a `int` value
   and the output parameters go first in the parameter list, followed
   by the object that a function is operating on, and then any other
   arguments the function may need.

 - If a function returns an object as a return value, that function is
   a getter and the object's lifetime is tied to the parent
   object. Objects which are returned as the first argument as a
21
   pointer-to-pointer are owned by the caller and it is responsible
22 23 24
   for freeing it. Strings are returned via `git_buf` in order to
   allow for re-use and safe freeing.

25
 - Most of what libgit2 does relates to I/O so as a general rule
26 27 28 29 30 31 32 33 34 35 36 37
   you should assume that any function can fail due to errors as even
   getting data from the filesystem can result in all sorts of errors
   and complex failure cases.

 - Paths inside the Git system are separated by a slash (0x2F). If a
   function accepts a path on disk, then backslashes (0x5C) are also
   accepted on Windows.

 - Do not mix allocators. If something has been allocated by libgit2,
   you do not know which is the right free function in the general
   case. Use the free functions provided for each object type.

38 39 40 41
## Compatibility

`libgit2` runs on many different platforms with many different compilers.

42 43 44 45 46 47 48 49 50 51 52
The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
(a.k.a. C89) compatible.

Internally, `libgit2` is written using a portable subset of C99 - in order
to maximize compatibility (e.g. with MSVC) we avoid certain C99
extensions.  Specifically, we keep local variable declarations at the tops
of blocks only and we avoid `//` style comments.

Also, to the greatest extent possible, we try to avoid lots of `#ifdef`s
inside the core code base.  This is somewhat unavoidable, but since it can
really hamper maintainability, we keep it to a minimum.
53 54 55 56 57 58 59 60 61 62 63 64

## Match Surrounding Code

If there is one rule to take away from this document, it is *new code should
match the surrounding code in a way that makes it impossible to distinguish
the new from the old.* Consistency is more important to us than anyone's
personal opinion about where braces should be placed or spaces vs. tabs.

If a section of code is being completely rewritten, it is okay to bring it
in line with the standards that are laid out here, but we will not accept
submissions that contain a large number of changes that are merely
reformatting.
65

66
## Naming Things
67

68 69 70 71 72
All external types and functions start with `git_` and all `#define` macros
start with `GIT_`.  The `libgit2` API is mostly broken into related
functional modules each with a corresponding header.  All functions in a
module should be named like `git_modulename_functioname()`
(e.g. `git_repository_open()`).
73

74 75
Functions with a single output parameter should name that parameter `out`.
Multiple outputs should be named `foo_out`, `bar_out`, etc.
76

77 78
Parameters of type `git_oid` should be named `id`, or `foo_id`.  Calls that
return an OID should be named `git_foo_id`.
79

80 81 82
Where a callback function is used, the function should also include a
user-supplied extra input that is a `void *` named "payload" that will be
passed through to the callback at each invocation.
83

84
## Typedefs
85

86 87 88
Wherever possible, use `typedef`.  In some cases, if a structure is just a
collection of function pointers, the pointer types don't need to be
separately typedef'd, but loose function pointer types should be.
89

90
## Exports
91 92 93

All exported functions must be declared as:

94
```c
95
GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
Ben Straub committed
96
```
97

98
## Internals
99

100
Functions whose *modulename* is followed by two underscores,
101
for example `git_odb__read_packed`, are semi-private functions.
102 103 104
They are primarily intended for use within the library itself,
and may disappear or change their signature in a future release.

105 106 107 108 109
## Parameters

Out parameters come first.

Whenever possible, pass argument pointers as `const`.  Some structures (such
110 111
as `git_repository` and `git_index`) have mutable internal structure that
prevents this.
112 113

Callbacks should always take a `void *` payload as their last parameter.
114 115
Callback pointers are grouped with their payloads, and typically come last
when passed as arguments:
116

117 118
```c
int git_foo(git_repository *repo, git_foo_cb callback, void *payload);
119 120 121 122 123 124 125 126 127 128
```

## Memory Ownership

Some APIs allocate memory which the caller is responsible for freeing; others
return a pointer into a buffer that's owned by some other object.  Make this
explicit in the documentation.

## Return codes

129 130 131 132 133 134 135 136
Most public APIs should return an `int` error code.  As is typical with most
C library functions, a zero value indicates success and a negative value
indicates failure.

Some bindings will transform these returned error codes into exception
types, so returning a semantically appropriate error code is important.
Check
[`include/git2/errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h)
137 138
for the return codes already defined.

139
In your implementation, use `git_error_set()` to provide extended error
140
information to callers.
141

142
If a `libgit2` function internally invokes another function that reports an
143
error, but the error is not propagated up, use `git_error_clear()` to prevent
144
callers from getting the wrong error message later on.
145 146


147
## Structs
148

149
Most public types should be opaque, e.g.:
150

Ben Straub committed
151
```C
152
typedef struct git_odb git_odb;
Ben Straub committed
153
```
154

155 156 157 158
...with allocation functions returning an "instance" created within
the library, and not within the application.  This allows the type
to grow (or shrink) in size without rebuilding client code.

159 160
To preserve ABI compatibility, include an `int version` field in all transparent
structures, and initialize to the latest version in the constructor call.
161 162
Increment the "latest" version whenever the structure changes, and try to only
append to the end of the structure.
163

164
## Option Structures
165

166 167 168 169
If a function's parameter count is too high, it may be desirable to package
up the options in a structure.  Make them transparent, include a version
field, and provide an initializer constant or constructor.  Using these
structures should be this easy:
170

171 172 173 174 175
```C
git_foo_options opts = GIT_FOO_OPTIONS_INIT;
opts.baz = BAZ_OPTION_ONE;
git_foo(&opts);
```
176

177
## Enumerations
178

179 180 181
Typedef all enumerated types.  If each option stands alone, use the enum
type for passing them as parameters; if they are flags to be OR'ed together,
pass them as `unsigned int` or `uint32_t` or some appropriate type.
182

183
## Code Layout
184

185 186
Try to keep lines less than 80 characters long.  This is a loose
requirement, but going significantly over 80 columns is not nice.
187

188 189 190 191 192 193 194 195
Use common sense to wrap most code lines; public function declarations
can use a couple of different styles:

```c
/** All on one line is okay if it fits */
GIT_EXTERN(int) git_foo_simple(git_oid *id);

/** Otherwise one argument per line is a good next step */
196
GIT_EXTERN(int) git_foo_id(
197 198 199
	git_oid **out,
	int a,
	int b);
200 201
```

202
Indent with tabs; set your editor's tab width to eight for best effect.
203

204 205 206
Avoid trailing whitespace and only commit Unix-style newlines (i.e. no CRLF
in the repository - just set `core.autocrlf` to true if you are writing code
on a Windows machine).
207

208
## Documentation
209

210
All comments should conform to Doxygen "javadoc" style conventions for
211 212
formatting the public API documentation.  Try to document every parameter,
and keep the comments up to date if you change the parameter list.
213

214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
## Public Header Template

Use this template when creating a new public header.

```C
#ifndef INCLUDE_git_${filename}_h__
#define INCLUDE_git_${filename}_h__

#include "git/common.h"

/**
 * @file git/${filename}.h
 * @brief Git some description
 * @defgroup git_${filename} some description routines
 * @ingroup Git
 * @{
 */
GIT_BEGIN_DECL

/* ... definitions ... */

/** @} */
GIT_END_DECL
#endif
Ben Straub committed
238
```
239

240 241 242 243 244 245 246 247
## Inlined functions

All inlined functions must be declared as:

```C
GIT_INLINE(result_type) git_modulename_functionname(arg_list);
```

248 249 250
`GIT_INLINE` (or `inline`) should not be used in public headers in order
to preserve ANSI C compatibility.

251 252
## Tests

Russell Belfer committed
253
`libgit2` uses the [clar](https://github.com/vmg/clar) testing framework.
254 255 256 257 258 259 260 261 262 263 264 265 266

All PRs should have corresponding tests.

* If the PR fixes an existing issue, the test should fail prior to applying
  the PR and succeed after applying it.
* If the PR is for new functionality, then the tests should exercise that
  new functionality to a certain extent.  We don't require 100% coverage
  right now (although we are getting stricter over time).

When adding new tests, we prefer if you attempt to reuse existing test data
(in `tests-clar/resources/`) if possible.  If you are going to add new test
repositories, please try to strip them of unnecessary files (e.g. sample
hooks, etc).