CODING_CONVENTIONS.md: Add preprocessor directive formatting

maribu · maribu · commit f431aab85642 · 2024-09-23T17:08:05.000+02:00
This explicitly spells out what informally has been the coding
convention for some time on preprocessor directives, making it
more transparent and easier to find.

This is particularly useful as the code base has at least three
different styles. Deducing what actually is the current policy
would require a details look at how the style has changed over
time, rather than being obvious from a quick `grep` over the
code base.
diff --git a/CODING_CONVENTIONS.md b/CODING_CONVENTIONS.md
@@ -162,6 +162,89 @@
 * For complex statements it is always good to use more parentheses - or split up
   the statement and simplify it.
 
+## Indentation of Preprocessor Directives
+
+Add two spaces of indent *after* the `#` per level of indent. Increment the
+indent when entering conditional compilation using `#if`/`#ifdef`/`#ifndef`
+(except for the include guard, which does not add to the indent). Treat indent
+for C language statements and C preprocessor directives independently.
+
+```
+/* BAD: */
+#if XOSC1
+#define XOSC XOSC1
+#define XOSC_NUM 1
+#elif XOSC2
+#define XOSC XSOC2
+#define XOSC_NUM 2
+#endif /* XOSC1/XOSC2 */
+```
+
+```
+/* GOOD: */
+#if XOSC1
+#  define XOSC XOSC1
+#  define XOSC_NUM 1
+#elif XOSC2
+#  define XOSC XSOC2
+#  define XOSC_NUM 2
+#endif
+```
+
+```
+/* BAD: */
+void init_foo(uint32_t param)
+{
+    (void)param;
+    #if HAS_FOO
+    switch (param) {
+    case CASE1:
+        do_foo_init_for_case1;
+        break;
+    #if HAS_CASE_2
+    case CASE2:
+        do_foo_init_for_case2;
+        break;
+        #endif
+    #endif
+}
+```
+
+```
+/* GOOD: */
+void init_foo(uint32_t param)
+{
+    (void)param;
+#if HAS_FOO
+    switch (param) {
+    case CASE1:
+        do_foo_init_for_case1;
+        break;
+#  if HAS_CASE_2
+    case CASE2:
+        do_foo_init_for_case2;
+        break;
+#  endif
+#endif
+}
+```
+
+### Reasoning
+
+Adding the indent does improve readability a lot, more than adding comments.
+Hence, we prefer the indent to allow reviewers to quickly grasp the structure
+of the code.
+
+Adding spaces before the `#` is not in compliance with the C standard (even
+though in practice compilers will be just fine with whitespace in front), but
+adding spaces afterwards is standard compliant. In either case, having the `#`
+at the beginning of the line makes it visually stand out from C statements,
+which eases reading the code.
+
+Using an indent width of 2 makes preprocessor directives visually more
+distinctive from C code, which helps to quickly understand the structure
+of code.
+
 ## Includes
 
 * The include of system headers (in <>-brackets) always precedes RIOT specific
@@ -171,7 +254,7 @@
   statement around includes of optional headers:
 ```c
 #ifdef MODULE_ABC
-#include "abc.h"
+#  include "abc.h"
 #endif
 ```
 
