diff --git a/CODING_STYLE.md b/CODING_STYLE.md index fb5022c49..6e2ad8562 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -1,8 +1,8 @@ LXC Coding Style Guide ====================== -In general the LXC project follows the Linux kernel coding style. There are -however are a few differences, these are outlined in this document. +In general the LXC project follows the Linux kernel coding style. However, +there are a few differences. They are outlined in this document. The Linux kernel coding style guide can be found within the kernel tree: @@ -83,15 +83,17 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html ## 3) Only use `/* */` Style Comments - Any comments that are added must use `/* */`. -- All comments should start on the same line as the opening `/*`. +- Single-line comments should start on the same line as the opening `/*`. - Single-line comments should simply be placed between `/* */`. For example: ```C /* Define pivot_root() if missing from the C library */ ``` -- Multi-line comments should end with the closing `*/` on a separate line. For +- Mutli-line comment should start on the next line following the opening + `/*`and should end with the closing `*/` on a separate line. For example: ```C - /* At this point the old-root is mounted on top of our new-root + /* + * At this point the old-root is mounted on top of our new-root * To unmounted it we must not be chdir()ed into it, so escape back * to old-root. */ @@ -109,16 +111,49 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html punctuation sign. - They should be descriptive, without being needlessly long. It is best to just use already existing error messages as examples. +- The commit message itself is not subject to rule 4), i.e. it should not be + wrapped at 80chars. This is to make it easy to grep for it. - Examples of acceptable error messages are: ```C SYSERROR("Failed to create directory \"%s\"", path); WARN("\"/dev\" directory does not exist. Proceeding without autodev being set up"); ``` -## 6) Return Error Codes +## 6) Set `errno` -- When writing a function that can fail in a non-binary way try to return - meaningful negative error codes (e.g. `return -EINVAL;`). +- Functions that can fail in a non-binary way should return `-1` and set + `errno` to a meaningful error code. + As a convenience LXC provides the `minus_one_set_errno` macro: + ```C + static int set_config_net_l2proxy(const char *key, const char *value, + struct lxc_conf *lxc_conf, void *data) + { + struct lxc_netdev *netdev = data; + unsigned int val = 0; + int ret; + + if (lxc_config_value_empty(value)) + return clr_config_net_l2proxy(key, lxc_conf, data); + + if (!netdev) + return minus_one_set_errno(EINVAL); + + ret = lxc_safe_uint(value, &val); + if (ret < 0) + return minus_one_set_errno(-ret); + + switch (val) { + case 0: + netdev->l2proxy = false; + return 0; + case 1: + netdev->l2proxy = true; + return 0; + } + + return minus_one_set_errno(EINVAL); + } + ``` ## 7) All Unexported Functions Must Be Declared `static` @@ -133,15 +168,17 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html ## 9) Declaring Variables - variables should be declared at the top of the function or at the beginning - of a new scope but **never** in the middle of a scope -1. uninitialized variables - - put base types before complex types - - put standard types defined by libc before types defined by LXC - - put multiple declarations of the same type on the same line + of a new scope but **never** in the middle of a scope. They should be ordered + in the following way: +1. automatically freed variables + - This specifically references variables cleaned up via the `cleanup` + attribute as supported by `gcc` and `clang`. 2. initialized variables - - put base types before complex types - - put standard types defined by libc before types defined by LXC - - put multiple declarations of the same type on the same line +3. uninitialized variables +General rules are: +- put base types before complex types +- put standard types defined by libc before types defined by LXC +- put multiple declarations of the same type on the same line - Examples of good declarations can be seen in the following function: ```C int lxc_clear_procs(struct lxc_conf *c, const char *key)