| libgit2 conventions |
| =================== |
| |
| Namespace Prefixes |
| ------------------ |
| |
| All types and functions start with 'git_'. |
| |
| All #define macros start with 'GIT_'. |
| |
| |
| Type Definitions |
| ---------------- |
| |
| Most types should be opaque, e.g.: |
| |
| ---- |
| typedef struct git_odb git_odb; |
| ---- |
| |
| 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. |
| |
| |
| Public Exported Function Definitions |
| ------------------------------------ |
| |
| All exported functions must be declared as: |
| |
| ---- |
| GIT_EXTERN(result_type) git_modulename_functionname(arg_list); |
| ---- |
| |
| |
| Semi-Private Exported Functions |
| ------------------------------- |
| |
| Functions whose modulename is followed by two underscores, |
| 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. |
| |
| |
| Calling Conventions |
| ------------------- |
| |
| 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_SUCCESS and < 0 for an error. |
| This permits common POSIX result testing: |
| |
| ---- |
| if (git_odb_open(&odb, path)) |
| abort("odb open failed"); |
| ---- |
| |
| Functions returning a pointer may return NULL instead of an int |
| if there is only one type of failure (ENOMEM). |
| |
| 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. |
| |
| |
| Documentation Fomatting |
| ----------------------- |
| |
| All comments should conform to Doxygen "javadoc" style conventions |
| for formatting the public API documentation. |
| |
| |
| Public Header Format |
| -------------------- |
| |
| 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 '_'. |
| |
| ---- |
| #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 |
| ---- |