CODING_STYLE

   1 - 8ch indent, no tabs
   2
   3 - Don't break code lines too eagerly. We do *not* force line breaks at
   4   80ch, all of today's screens should be much larger than that. But
   5   then again, don't overdo it, ~140ch should be enough really.
   6
   7 - Variables and functions *must* be static, unless they have a
   8   prototype, and are supposed to be exported.
   9
  10 - structs in MixedCase (with exceptions, such as public API structs),
  11   variables + functions in lower_case.
  12
  13 - The destructors always unregister the object from the next bigger
  14   object, not the other way around
  15
  16 - To minimize strict aliasing violations, we prefer unions over casting
  17
  18 - For robustness reasons, destructors should be able to destruct
  19   half-initialized objects, too
  20
  21 - Error codes are returned as negative Exxx. e.g. return -EINVAL. There
  22   are some exceptions: for constructors, it is OK to return NULL on
  23   OOM. For lookup functions, NULL is fine too for "not found".
  24
  25   Be strict with this. When you write a function that can fail due to
  26   more than one cause, it *really* should have "int" as return value
  27   for the error code.
  28
  29 - Do not bother with error checking whether writing to stdout/stderr
  30   worked.
  31
  32 - Do not log errors from "library" code, only do so from "main
  33   program" code. (With one exception: it is OK to log with DEBUG level
  34   from any code, with the exception of maybe inner loops).
  35
  36 - Always check OOM. There is no excuse. In program code, you can use
  37   "log_oom()" for then printing a short message, but not in "library" code.
  38
  39 - Do not issue NSS requests (that includes user name and host name
  40   lookups) from PID 1 as this might trigger deadlocks when those
  41   lookups involve synchronously talking to services that we would need
  42   to start up
  43
  44 - Do not synchronously talk to any other service from PID 1, due to
  45   risk of deadlocks
  46
  47 - Avoid fixed-size string buffers, unless you really know the maximum
  48   size and that maximum size is small. They are a source of errors,
  49   since they possibly result in truncated strings. It is often nicer
  50   to use dynamic memory, alloca() or VLAs. If you do allocate fixed-size
  51   strings on the stack, then it is probably only OK if you either
  52   use a maximum size such as LINE_MAX, or count in detail the maximum
  53   size a string can have. (DECIMAL_STR_MAX and DECIMAL_STR_WIDTH
  54   macros are your friends for this!)
  55
  56   Or in other words, if you use "char buf[256]" then you are likely
  57   doing something wrong!
  58
  59 - Stay uniform. For example, always use "usec_t" for time
  60   values. Do not mix usec and msec, and usec and whatnot.
  61
  62 - Make use of _cleanup_free_ and friends. It makes your code much
  63   nicer to read!
  64
  65 - Be exceptionally careful when formatting and parsing floating point
  66   numbers. Their syntax is locale dependent (i.e. "5.000" in en_US is
  67   generally understood as 5, while on de_DE as 5000.).
  68
  69 - Try to use this:
  70
  71       void foo() {
  72       }
  73
  74   instead of this:
  75
  76       void foo()
  77       {
  78       }
  79
  80   But it is OK if you do not.
  81
  82 - Single-line "if" blocks should not be enclosed in {}. Use this:
  83
  84   if (foobar)
  85           waldo();
  86
  87   instead of this:
  88
  89   if (foobar) {
  90           waldo();
  91   }
  92
  93 - Do not write "foo ()", write "foo()".
  94
  95 - Please use streq() and strneq() instead of strcmp(), strncmp() where applicable.
  96
  97 - Please do not allocate variables on the stack in the middle of code,
  98   even if C99 allows it. Wrong:
  99
 100   {
 101           a = 5;
 102           int b;
 103           b = a;
 104   }
 105
 106   Right:
 107
 108   {
 109           int b;
 110           a = 5;
 111           b = a;
 112   }
 113
 114 - Unless you allocate an array, "double" is always the better choice
 115   than "float". Processors speak "double" natively anyway, so this is
 116   no speed benefit, and on calls like printf() "float"s get promoted
 117   to "double"s anyway, so there is no point.
 118
 119 - Do not invoke functions when you allocate variables on the stack. Wrong:
 120
 121   {
 122           int a = foobar();
 123           uint64_t x = 7;
 124   }
 125
 126   Right:
 127
 128   {
 129           int a;
 130           uint64_t x = 7;
 131
 132           a = foobar();
 133   }
 134
 135 - Use "goto" for cleaning up, and only use it for that. i.e. you may
 136   only jump to the end of a function, and little else. Never jump
 137   backwards!
 138
 139 - Think about the types you use. If a value cannot sensibly be
 140   negative, do not use "int", but use "unsigned".
 141
 142 - Do not use types like "short". They *never* make sense. Use ints,
 143   longs, long longs, all in unsigned+signed fashion, and the fixed
 144   size types uint32_t and so on, as well as size_t, but nothing else.
 145
 146 - Public API calls (i.e. functions exported by our shared libraries)
 147   must be marked "_public_" and need to be prefixed with "sd_". No
 148   other functions should be prefixed like that.
 149
 150 - In public API calls, you *must* validate all your input arguments for
 151   programming error with assert_return() and return a sensible return
 152   code. In all other calls, it is recommended to check for programming
 153   errors with a more brutal assert(). We are more forgiving to public
 154   users then for ourselves! Note that assert() and assert_return()
 155   really only should be used for detecting programming errors, not for
 156   runtime errors. assert() and assert_return() by usage of _likely_()
 157   inform the compiler that he should not expect these checks to fail,
 158   and they inform fellow programmers about the expected validity and
 159   range of parameters.
 160
 161 - Never use strtol(), atoi() and similar calls. Use safe_atoli(),
 162   safe_atou32() and suchlike instead. They are much nicer to use in
 163   most cases and correctly check for parsing errors.
 164
 165 - For every function you add, think about whether it is a "logging"
 166   function or a "non-logging" function. "Logging" functions do logging
 167   on their own, "non-logging" function never log on their own and
 168   expect their callers to log. All functions in "library" code,
 169   i.e. in src/shared/ and suchlike must be "non-logging". Every time a
 170   "logging" function calls a "non-logging" function, it should log
 171   about the resulting errors. If a "logging" function calls another
 172   "logging" function, then it should not generate log messages, so
 173   that log messages are not generated twice for the same errors.
 174
 175 - Avoid static variables, except for caches and very few other
 176   cases. Think about thread-safety! While most of our code is never
 177   used in threaded environments, at least the library code should make
 178   sure it works correctly in them. Instead of doing a lot of locking
 179   for that, we tend to prefer using TLS to do per-thread caching (which
 180   only works for small, fixed-size cache objects), or we disable
 181   caching for any thread that is not the main thread. Use
 182   is_main_thread() to detect whether the calling thread is the main
 183   thread.
 184
 185 - Command line option parsing:
 186   - Do not print full help() on error, be specific about the error.
 187   - Do not print messages to stdout on error.
 188   - Do not POSIX_ME_HARDER unless necessary, i.e. avoid "+" in option string.
 189
 190 - Do not write functions that clobber call-by-reference variables on
 191   failure. Use temporary variables for these cases and change the
 192   passed in variables only on success.
 193
 194 - When you allocate a file descriptor, it should be made O_CLOEXEC
 195   right from the beginning, as none of our files should leak to forked
 196   binaries by default. Hence, whenever you open a file, O_CLOEXEC must
 197   be specified, right from the beginning.