chiark / gitweb /
memfd: rename memfd.h to memfd-util.h to avoid any confusion with any libc provided...
[elogind.git] / 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.