proxmox-mirrors/libgit2
1
0
Fork 0
mirror of https://git.proxmox.com/git/libgit2 synced 2025-06-19 22:44:42 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Rewrite conventions to be more complete

Browse Source
This commit is contained in:
Ben Straub 2012-11-21 13:42:12 -07:00
parent ee72ffd060
commit 24aec6db55
1 changed files with 127 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
CONVENTIONS.md
View File

@ -1,107 +1,163 @@
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_'.
Type Definitions ## Naming Things
----------------
Most types should be opaque, e.g.: All types and functions start with `git_`, and all #define macros start with `GIT_`.
```C Functions with a single output parameter should name that parameter `out`.
typedef struct git_odb git_odb; Multiple outputs should be named `foo_out`, `bar_out`, etc.
```
with allocation functions returning an "instance" created within Parameters of type `git_oid` should be named `id`, or `foo_id`. Calls that
the library, and not within the application. This allows the type return an OID should be named `git_foo_id`.
to grow (or shrink) in size without rebuilding client code.
Where there is a callback passed in, the `void *` that is passed into it should
be named "payload".
Public Exported Function Definitions ## 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.
## Exports
All exported functions must be declared as: All exported functions must be declared as:
```C ```C
GIT_EXTERN(result_type) git_modulename_functionname(arg_list); GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
``` ```
## Internals
Semi-Private Exported Functions
-------------------------------
Functions whose modulename is followed by two underscores, 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, They are primarily intended for use within the library itself,
and may disappear or change their signature in a future release. and may disappear or change their signature in a future release.
## Parameters
Calling Conventions Out parameters come first.
-------------------
Functions should prefer to return a 'int' to indicate success or Whenever possible, pass argument pointers as `const`. Some structures (such
failure and supply any output through the first argument (or first as `git_repository` and `git_index`) have internal structure that prevents
few arguments if multiple outputs are supplied). this.
int status codes are 0 for GIT_OK and < 0 for an error. Callbacks should always take a `void *` payload as their last parameter.
This permits common POSIX result testing: Callback pointers are grouped with their payloads, and come last when passed as
arguments:
```C ```C
if (git_odb_open(&odb, path)) int foo(git_repository *repo, git_foo_cb callback, void *payload);
abort("odb open failed");
``` ```
Functions returning a pointer may return NULL instead of an int
if there is only one type of failure (GIT_ENOMEM).
Functions returning a pointer may also return NULL if the common ## Memory Ownership
case needed by the application is strictly success/failure and a
(possibly slower) function exists that the caller can use to get Some APIs allocate memory which the caller is responsible for freeing; others
more detailed information. Parsing common data structures from return a pointer into a buffer that's owned by some other object. Make this
on-disk formats is a good example of this pattern; in general a explicit in the documentation.
"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 ## Return codes
-----------------------
All comments should conform to Doxygen "javadoc" style conventions Return an `int` when a public API can fail in multiple ways. These may be
for formatting the public API documentation. 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.
If an error is not to be propagated, use `giterr_clear` to prevent callers from
getting the wrong error message later on.
Public Header Format ## Opaque Structs
--------------------
All public headers defining types, functions or macros must use Most types should be opaque, e.g.:
the following form, where ${filename} is the name of the file,
after replacing non-identifier characters with '_'.
```C ```C
#ifndef INCLUDE_git_${filename}_h__ typedef struct git_odb git_odb;
#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
``` ```
...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.
## 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:
```C
git_foo_options opts = GIT_FOO_OPTIONS_INIT;
opts.baz = BAZ_OPTION_ONE;
git_foo(&opts);
```
## 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`.
## Code Layout
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
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.
## Documentation
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.
## 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
```