-libgit2 conventions
-===================
+# Libgit2 Conventions
-Namespace Prefixes
-------------------
+We like to keep the source consistent and readable. Herein are some guidelines
+that should help with that.
-All types and functions start with 'git_'.
-All #define macros start with 'GIT_'.
+## Naming Things
+All types and functions start with `git_`, and all #define macros start with `GIT_`.
-Type Definitions
-----------------
+Functions with a single output parameter should name that parameter `out`.
+Multiple outputs should be named `foo_out`, `bar_out`, etc.
-Most types should be opaque, e.g.:
+Parameters of type `git_oid` should be named `id`, or `foo_id`. Calls that
+return an OID should be named `git_foo_id`.
-```C
- typedef struct git_odb git_odb;
-```
+Where there is a callback passed in, the `void *` that is passed into it should
+be named "payload".
-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.
+## Typedef
+Wherever possible, use `typedef`. 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.
-Public Exported Function Definitions
-------------------------------------
+## Exports
All exported functions must be declared as:
```C
- GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
+GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
```
-
-Semi-Private Exported Functions
--------------------------------
+## Internals
Functions whose modulename is followed by two underscores,
-for example 'git_odb__read_packed', are semi-private functions.
+for example `git_odb__read_packed`, are semi-private functions.
They are primarily intended for use within the library itself,
and may disappear or change their signature in a future release.
+## Parameters
+
+Out parameters come first.
+
+Whenever possible, pass argument pointers as `const`. Some structures (such
+as `git_repository` and `git_index`) have internal structure that prevents
+this.
+
+Callbacks should always take a `void *` payload as their last parameter.
+Callback pointers are grouped with their payloads, and come last when passed as
+arguments:
+
+```C
+int foo(git_repository *repo, git_foo_cb callback, void *payload);
+```
+
+
+## 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
+
+Return an `int` when a public API can fail in multiple ways. These may be
+transformed into exception types in some bindings, so returning a semantically
+appropriate error code is important. Check
+[`errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h)
+for the return codes already defined.
+
+Use `giterr_set` to provide extended error information to callers.
-Calling Conventions
--------------------
+If an error is not to be propagated, use `giterr_clear` to prevent callers from
+getting the wrong error message later on.
-Functions should prefer to return a 'int' to indicate success or
-failure and supply any output through the first argument (or first
-few arguments if multiple outputs are supplied).
-int status codes are 0 for GIT_OK and < 0 for an error.
-This permits common POSIX result testing:
+## Opaque Structs
+
+Most types should be opaque, e.g.:
```C
- if (git_odb_open(&odb, path))
- abort("odb open failed");
+typedef struct git_odb git_odb;
```
-Functions returning a pointer may return NULL instead of an int
-if there is only one type of failure (GIT_ENOMEM).
+...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.
+
+To preserve ABI compatibility, include an `int version` field in all opaque
+structures, and initialize to the latest version in the construction call.
+Increment the "latest" version whenever the structure changes, and try to only
+append to the end of the structure.
-Functions returning a pointer may also return NULL if the common
-case needed by the application is strictly success/failure and a
-(possibly slower) function exists that the caller can use to get
-more detailed information. Parsing common data structures from
-on-disk formats is a good example of this pattern; in general a
-"corrupt" entity can be treated as though it does not exist but
-a more sophisticated "fsck" support function can report how the
-entity is malformed.
+## Option Structures
+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:
-Documentation Fomatting
------------------------
+```C
+git_foo_options opts = GIT_FOO_OPTIONS_INIT;
+opts.baz = BAZ_OPTION_ONE;
+git_foo(&opts);
+```
-All comments should conform to Doxygen "javadoc" style conventions
-for formatting the public API documentation.
+## Enumerations
+Typedef all enumerated types. If each option stands alone, use the enum type
+for passing them as parameters; if they are flags, pass them as `unsigned int`.
-Public Header Format
---------------------
+## Code Layout
-All public headers defining types, functions or macros must use
-the following form, where ${filename} is the name of the file,
-after replacing non-identifier characters with '_'.
+Try to keep lines less than 80 characters long. Use common sense to wrap most
+code lines; public function declarations should use this convention:
```C
- #ifndef INCLUDE_git_${filename}_h__
- #define INCLUDE_git_${filename}_h__
+GIT_EXTERN(int) git_foo_id(
+ git_oid **out,
+ int a,
+ int b);
+```
+
+Public headers are indented with spaces, three to a tab. Internal code is
+indented with tabs; set your editor's tab width to 3 for best effect.
+
- #include "git/common.h"
+## Documentation
- /**
- * @file git/${filename}.h
- * @brief Git some description
- * @defgroup git_${filename} some description routines
- * @ingroup Git
- * @{
- */
- GIT_BEGIN_DECL
+All comments should conform to Doxygen "javadoc" style conventions for
+formatting the public API documentation. Try to document every parameter, and
+keep the comments up to date if you change the parameter list.
- ... definitions ...
- /** @} */
- GIT_END_DECL
- #endif
+## 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
```
+
+
projects / libgit2.git / commitdiff