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. i.e. 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 usec mix 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 - Do not write "foo ()", write "foo()".
  83
  84 - Please use streq() and strneq() instead of strcmp(), strncmp() where applicable.
  85
  86 - Please do not allocate variables on the stack in the middle of code,
  87   even if C99 allows it. Wrong:
  88
  89   {
  90           a = 5;
  91           int b;
  92           b = a;
  93   }
  94
  95   Right:
  96
  97   {
  98           int b;
  99           a = 5;
 100           b = a;
 101   }
 102
 103 - Unless you allocate an array, "double" is always the better choice
 104   than "float". Processors speak "double" natively anyway, so this is
 105   no speed benefit, and on calls like printf() "float"s get promoted
 106   to "double"s anyway, so there is no point.
 107
 108 - Do not invoke functions when you allocate variables on the stack. Wrong:
 109
 110   {
 111           int a = foobar();
 112           uint64_t x = 7;
 113   }
 114
 115   Right:
 116
 117   {
 118           int a;
 119           uint64_t x = 7;
 120
 121           a = foobar();
 122   }
 123
 124 - Use "goto" for cleaning up, and only use it for that. i.e. you may
 125   only jump to the end of a function, and little else. Never jump
 126   backwards!
 127
 128 - Think about the types you use. If a value cannot sensibly be
 129   negative, do not use "int", but use "unsigned".
 130
 131 - Do not use types like "short". They *never* make sense. Use ints,
 132   longs, long longs, all in unsigned+signed fashion, and the fixed
 133   size types uint32_t and so on, as well as size_t, but nothing else.
 134
 135 - Public API calls (i.e. functions exported by our shared libraries)
 136   must be marked "_public_" and need to be prefixed with "sd_". No
 137   other functions should be prefixed like that.
 138
 139 - In public API calls, you *must* validate all your input arguments for
 140   programming error with assert_return() and return a sensible return
 141   code. In all other calls, it is recommended to check for programming
 142   errors with a more brutal assert(). We are more forgiving to public
 143   users then for ourselves! Note that assert() and assert_return()
 144   really only should be used for detecting programming errors, not for
 145   runtime errors. assert() and assert_return() by usage of _likely_()
 146   inform the compiler that he should not expect these checks to fail,
 147   and they inform fellow programmers about the expected validity and
 148   range of parameters.
 149
 150 - Never use strtol(), atoi() and similar calls. Use safe_atoli(),
 151   safe_atou32() and suchlike instead. They are much nicer to use in
 152   most cases and correctly check for parsing errors.
 153
 154 - For every function you add, think about whether it is a "logging"
 155   function or a "non-logging" function. "Logging" functions do logging
 156   on their own, "non-logging" function never log on their own and
 157   expect their callers to log. All functions in "library" code,
 158   i.e. in src/shared/ and suchlike must be "non-logging". Every time a
 159   "logging" function calls a "non-logging" function, it should log
 160   about the resulting errors. If a "logging" function calls another
 161   "logging" function, then it should not generate log messages, so
 162   that log messages are not generated twice for the same errors.
 163
 164 - Avoid static variables, except for caches and very few other
 165   cases. Think about thread-safety! While most of our code is never
 166   used in threaded environments, at least the library code should make
 167   sure it works correctly in them. Instead of doing a lot of locking
 168   for that, we tend to prefer using TLS to do per-thread caching (which
 169   only works for small, fixed-size cache objects), or we disable
 170   caching for any thread that is not the main thread. Use
 171   is_main_thread() to detect whether the calling thread is the main
 172   thread.
 173
 174 - Option parsing:
 175   - Do not print full help() on error, be specific about the error.
 176   - Do not print messages to stdout on error.
 177   - Do not POSIX_ME_HARDER unless necessary, i.e. avoid "+" in option string.