[lxc-devel] [lxc/master] coding style: update

[brauner on Github]

A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 364 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20190510/faba022e/attachment.bin>
-------------- next part --------------
From 24418a9d45ceb626d42b71106c1c9ce4602500c1 Mon Sep 17 00:00:00 2001
From: Christian Brauner <christian.brauner at ubuntu.com>
Date: Fri, 10 May 2019 13:15:25 +0200
Subject: [PATCH] coding style: update

Signed-off-by: Christian Brauner <christian.brauner at ubuntu.com>
---
 CODING_STYLE.md | 69 +++++++++++++++++++++++++++++++++++++------------
 1 file changed, 53 insertions(+), 16 deletions(-)

diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index fb5022c49c..0b0ec08bb0 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.  Hwoever,
+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)