CONVENTIONS

   1 libgit2 conventions
   2 ===================
   3
   4 Namespace Prefixes
   5 ------------------
   6
   7 All types and functions start with 'git_'.
   8
   9 All #define macros start with 'GIT_'.
  10
  11
  12 Type Definitions
  13 ----------------
  14
  15 Most types should be opaque, e.g.:
  16
  17 ----
  18         typedef struct git_odb git_odb;
  19 ----
  20
  21 with allocation functions returning an "instance" created within
  22 the library, and not within the application.  This allows the type
  23 to grow (or shrink) in size without rebuilding client code.
  24
  25
  26 Public Exported Function Definitions
  27 ------------------------------------
  28
  29 All exported functions must be declared as:
  30
  31 ----
  32         GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
  33 ----
  34
  35
  36 Semi-Private Exported Functions
  37 -------------------------------
  38
  39 Functions whose modulename is followed by two underscores,
  40 for example 'git_odb__read_packed', are semi-private functions.
  41 They are primarily intended for use within the library itself,
  42 and may disappear or change their signature in a future release.
  43
  44
  45 Calling Conventions
  46 -------------------
  47
  48 Functions should prefer to return a 'int' to indicate success or
  49 failure and supply any output through the first argument (or first
  50 few arguments if multiple outputs are supplied).
  51
  52 int status codes are 0 for GIT_SUCCESS and < 0 for an error.
  53 This permits common POSIX result testing:
  54
  55 ----
  56         if (git_odb_open(&odb, path))
  57                 abort("odb open failed");
  58 ----
  59
  60 Functions returning a pointer may return NULL instead of an int
  61 if there is only one type of failure (ENOMEM).
  62
  63 Functions returning a pointer may also return NULL if the common
  64 case needed by the application is strictly success/failure and a
  65 (possibly slower) function exists that the caller can use to get
  66 more detailed information.  Parsing common data structures from
  67 on-disk formats is a good example of this pattern; in general a
  68 "corrupt" entity can be treated as though it does not exist but
  69 a more sophisticated "fsck" support function can report how the
  70 entity is malformed.
  71
  72
  73 Documentation Fomatting
  74 -----------------------
  75
  76 All comments should conform to Doxygen "javadoc" style conventions
  77 for formatting the public API documentation.
  78
  79
  80 Public Header Format
  81 --------------------
  82
  83 All public headers defining types, functions or macros must use
  84 the following form, where ${filename} is the name of the file,
  85 after replacing non-identifier characters with '_'.
  86
  87 ----
  88         #ifndef INCLUDE_git_${filename}_h__
  89         #define INCLUDE_git_${filename}_h__
  90
  91         #include "git/common.h"
  92
  93         /**
  94          * @file git/${filename}.h
  95          * @brief Git some description
  96          * @defgroup git_${filename} some description routines
  97          * @ingroup Git
  98          * @{
  99          */
 100         GIT_BEGIN_DECL
 101
 102         ... definitions ...
 103
 104         /** @} */
 105         GIT_END_DECL
 106         #endif
 107 ----