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