CODING_STYLE revision 7f8bf08f9036de419ad14c55b61eda74c6659d3a
afe3ab588a6b2992efe5a9b22ed038545ba3cdbfLennart Poettering- 8ch indent, no tabs
b3ae710c251d0ce5cf2cef63208e325497b5e323Zbigniew Jędrzejewski-Szmek- Don't break code lines too eagerly. We do *not* force line breaks at
b3ae710c251d0ce5cf2cef63208e325497b5e323Zbigniew Jędrzejewski-Szmek 80ch, all of today's screens should be much larger than that. But
f957632b960a0a42999b38ded7089fa602b41745Kay Sievers then again, don't overdo it, ~140ch should be enough really.
f957632b960a0a42999b38ded7089fa602b41745Kay Sievers- Variables and functions *must* be static, unless they have a
f957632b960a0a42999b38ded7089fa602b41745Kay Sievers prototype, and are supposed to be exported.
20ffc4c4a9226b0e45cc02ad9c0108981626c0bbKay Sievers- structs in MixedCase (with exceptions, such as public API structs),
afe3ab588a6b2992efe5a9b22ed038545ba3cdbfLennart Poettering variables + functions in lower_case.
d19e85f0d474ed1882561b458d528cbae49f640eZbigniew Jędrzejewski-Szmek- The destructors always unregister the object from the next bigger
d19e85f0d474ed1882561b458d528cbae49f640eZbigniew Jędrzejewski-Szmek object, not the other way around
d19e85f0d474ed1882561b458d528cbae49f640eZbigniew Jędrzejewski-Szmek- To minimize strict aliasing violations, we prefer unions over casting
afe3ab588a6b2992efe5a9b22ed038545ba3cdbfLennart Poettering- For robustness reasons, destructors should be able to destruct
afe3ab588a6b2992efe5a9b22ed038545ba3cdbfLennart Poettering half-initialized objects, too
f38afcd0c7f558ca5bf0854b42f8c6954f8ad7f3Lennart Poettering- Error codes are returned as negative Exxx. e.g. return -EINVAL. There
f85857df75cfedbc0d10b8ca2400188dc8f4c22eLennart Poettering are some exceptions: for constructors, it is OK to return NULL on
f38afcd0c7f558ca5bf0854b42f8c6954f8ad7f3Lennart Poettering OOM. For lookup functions, NULL is fine too for "not found".
f38afcd0c7f558ca5bf0854b42f8c6954f8ad7f3Lennart Poettering Be strict with this. When you write a function that can fail due to
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering more than one cause, it *really* should have "int" as return value
81429136905a6204875174b60a179333b7f3c9e4Kay Sievers for the error code.
58f55364fa00a6a4706df2c4a01c6967f432e531Lennart Poettering- Do not bother with error checking whether writing to stdout/stderr
83a1ff25e5228b0a5b2cc942fd4f964d10bb73b0Zbigniew Jędrzejewski-Szmek- Do not log errors from "library" code, only do so from "main
83a1ff25e5228b0a5b2cc942fd4f964d10bb73b0Zbigniew Jędrzejewski-Szmek program" code. (With one exception: it is OK to log with DEBUG level
83a1ff25e5228b0a5b2cc942fd4f964d10bb73b0Zbigniew Jędrzejewski-Szmek from any code, with the exception of maybe inner loops).
81429136905a6204875174b60a179333b7f3c9e4Kay Sievers- Always check OOM. There is no excuse. In program code, you can use
fbe1a1a94f19112d7e5d60c40d87487ad24e2ce4Lennart Poettering "log_oom()" for then printing a short message, but not in "library" code.
e3286870fdf20c3c93e944b24fd9af53620f7dbaLennart Poettering- Do not issue NSS requests (that includes user name and host name
e3286870fdf20c3c93e944b24fd9af53620f7dbaLennart Poettering lookups) from PID 1 as this might trigger deadlocks when those
e3286870fdf20c3c93e944b24fd9af53620f7dbaLennart Poettering lookups involve synchronously talking to services that we would need
e3286870fdf20c3c93e944b24fd9af53620f7dbaLennart Poettering- Do not synchronously talk to any other service from PID 1, due to
e3286870fdf20c3c93e944b24fd9af53620f7dbaLennart Poettering risk of deadlocks
a195cbad3796dfda3d1016e4819c612c859e3c7bLennart Poettering- Avoid fixed-size string buffers, unless you really know the maximum
a195cbad3796dfda3d1016e4819c612c859e3c7bLennart Poettering size and that maximum size is small. They are a source of errors,
75e52a16f9ef476f1d18ec6d9c84e00149b80d03Lennart Poettering since they possibly result in truncated strings. It is often nicer
75e52a16f9ef476f1d18ec6d9c84e00149b80d03Lennart Poettering to use dynamic memory, alloca() or VLAs. If you do allocate fixed-size
f3589f7bc657765d7635b3ead81b3620e51a9028Lennart Poettering strings on the stack, then it is probably only OK if you either
f3589f7bc657765d7635b3ead81b3620e51a9028Lennart Poettering use a maximum size such as LINE_MAX, or count in detail the maximum
8514b67754c5ff7fa628929b3d27131010c21842Lennart Poettering size a string can have. (DECIMAL_STR_MAX and DECIMAL_STR_WIDTH
8514b67754c5ff7fa628929b3d27131010c21842Lennart Poettering macros are your friends for this!)
6c78f43c7b0e54e695af49917fda79b584f46830Lennart Poettering Or in other words, if you use "char buf[256]" then you are likely
7b0fce617c48eda32b2d4e04b5f0e4376e8c0106Lennart Poettering doing something wrong!
7b0fce617c48eda32b2d4e04b5f0e4376e8c0106Lennart Poettering- Stay uniform. For example, always use "usec_t" for time
7b0fce617c48eda32b2d4e04b5f0e4376e8c0106Lennart Poettering values. Do not mix usec and msec, and usec and whatnot.
b568ef14a75dffb7182e0acbdec743b31df2a597Lennart Poettering- Make use of _cleanup_free_ and friends. It makes your code much
c2d5b3c94d0c082ef29597fb230f8b88b124bab8Lennart Poettering nicer to read!
264b8070715d2d19344c4991ace21147d998f56dLennart Poettering- Be exceptionally careful when formatting and parsing floating point
4ecd22142543aac55ddac1da3b7d6882c009d637Lennart Poettering numbers. Their syntax is locale dependent (i.e. "5.000" in en_US is
4ecd22142543aac55ddac1da3b7d6882c009d637Lennart Poettering generally understood as 5, while on de_DE as 5000.).
7e27f3121e5a10629302b5221eb21345f832724aLennart Poettering- Try to use this:
25e14499c4c5b02229d05a5bc26c3693ade5f987Lennart Poettering instead of this:
8483d73ff158ee0d51ccbba09a470cc6ae9b071aLennart Poettering But it is OK if you do not.
8483d73ff158ee0d51ccbba09a470cc6ae9b071aLennart Poettering- Single-line "if" blocks should not be enclosed in {}. Use this:
8483d73ff158ee0d51ccbba09a470cc6ae9b071aLennart Poettering instead of this:
25e773eeb4f853804e1bf0dbd9a184f23e9b2a97Kay Sievers if (foobar) {
384a4be2b00cb95ce215dd343cc9aa77adc9b1ecLennart Poettering- Do not write "foo ()", write "foo()".
706d97503df83d141d241b645d2c920d691b3d62Lennart Poettering- Please use streq() and strneq() instead of strcmp(), strncmp() where applicable.
3bcde97e8502c48b53f7420e2433ca68e601662dLennart Poettering- Please do not allocate variables on the stack in the middle of code,
3bcde97e8502c48b53f7420e2433ca68e601662dLennart Poettering even if C99 allows it. Wrong:
14a32924c9b46817c92ae11c1147a59dcb62012bLennart Poettering- Unless you allocate an array, "double" is always the better choice
563b1bdc09efe0cf94dd3f514f30376ca854c1ceLennart Poettering than "float". Processors speak "double" natively anyway, so this is
563b1bdc09efe0cf94dd3f514f30376ca854c1ceLennart Poettering no speed benefit, and on calls like printf() "float"s get promoted
5dcf983854c2e8314dbee239180255490ec8ae1cLennart Poettering to "double"s anyway, so there is no point.
5dcf983854c2e8314dbee239180255490ec8ae1cLennart Poettering- Do not invoke functions when you allocate variables on the stack. Wrong:
ed220efd6657822332b9563ec53c5ab9f3c33220Lennart Poettering int a = foobar();
ed220efd6657822332b9563ec53c5ab9f3c33220Lennart Poettering uint64_t x = 7;
41488fe9024a8955d19811620fd55dcc56a5b2baLennart Poettering uint64_t x = 7;
1dbe0a6efda7b1d35957eab7e1d56a2c69d806d9Lennart Poettering- Use "goto" for cleaning up, and only use it for that. i.e. you may
1dbe0a6efda7b1d35957eab7e1d56a2c69d806d9Lennart Poettering only jump to the end of a function, and little else. Never jump
b873d33ec9583c92a0c2bc6807d010720fa31595Lennart Poettering- Think about the types you use. If a value cannot sensibly be
9d6db739ce1eaa3eace21801fd606d523b73c8f4Lennart Poettering negative, do not use "int", but use "unsigned".
1dbe0a6efda7b1d35957eab7e1d56a2c69d806d9Lennart Poettering- Do not use types like "short". They *never* make sense. Use ints,
9d6db739ce1eaa3eace21801fd606d523b73c8f4Lennart Poettering longs, long longs, all in unsigned+signed fashion, and the fixed
ff3d6560bead6879a2fed1bf99bfe8273b3723f1Zbigniew Jędrzejewski-Szmek size types uint32_t and so on, as well as size_t, but nothing else.
151226ab4bf276d60d51864330a99f886b923697Zbigniew Jędrzejewski-Szmek- Public API calls (i.e. functions exported by our shared libraries)
23c4091dc2b85d117512e89233fdeb47d1ff3d92Lennart Poettering must be marked "_public_" and need to be prefixed with "sd_". No
23c4091dc2b85d117512e89233fdeb47d1ff3d92Lennart Poettering other functions should be prefixed like that.
0f47ed0a052c0da743404f23ac3532aaabd23655Lennart Poettering- In public API calls, you *must* validate all your input arguments for
9d6db739ce1eaa3eace21801fd606d523b73c8f4Lennart Poettering programming error with assert_return() and return a sensible return
bc07548926ec5ed7b13df8d3656654f238e0b9a7Lennart Poettering code. In all other calls, it is recommended to check for programming
bc07548926ec5ed7b13df8d3656654f238e0b9a7Lennart Poettering errors with a more brutal assert(). We are more forgiving to public
b6b63571ae3eca1741d54172922961af972b8f20Lennart Poettering users then for ourselves! Note that assert() and assert_return()
279f036675536d55c901562b49f9df146af1a0e3Lennart Poettering really only should be used for detecting programming errors, not for
279f036675536d55c901562b49f9df146af1a0e3Lennart Poettering runtime errors. assert() and assert_return() by usage of _likely_()
3f77a1b19f5a8ce33566f7f6e28e94c08ea30841Kay Sievers inform the compiler that he should not expect these checks to fail,
e2a69298819b58f008be61d314f8ab95ccaec427Lennart Poettering and they inform fellow programmers about the expected validity and
e2a69298819b58f008be61d314f8ab95ccaec427Lennart Poettering range of parameters.
2834ffe78d7fd8be118429aa1449ac72641638c2Lennart Poettering- Never use strtol(), atoi() and similar calls. Use safe_atoli(),
a940778fb1dd16479f455bab3ac6cbdbc5b06165Lennart Poettering safe_atou32() and suchlike instead. They are much nicer to use in
a940778fb1dd16479f455bab3ac6cbdbc5b06165Lennart Poettering most cases and correctly check for parsing errors.
3c779fa59d1825d7db2a9516669d34ded7916913Lennart Poettering- For every function you add, think about whether it is a "logging"
a940778fb1dd16479f455bab3ac6cbdbc5b06165Lennart Poettering function or a "non-logging" function. "Logging" functions do logging
a01647e53727107d82382bc5c9d98c894e8f386cLennart Poettering on their own, "non-logging" function never log on their own and
3de03738fc970496d2d3da668c72767a48ccc41bLennart Poettering expect their callers to log. All functions in "library" code,
3de03738fc970496d2d3da668c72767a48ccc41bLennart Poettering i.e. in src/shared/ and suchlike must be "non-logging". Every time a
2b1c3767515672dfd0f5e0a9c9d7ac3a16a6a361Lennart Poettering "logging" function calls a "non-logging" function, it should log
2b1c3767515672dfd0f5e0a9c9d7ac3a16a6a361Lennart Poettering about the resulting errors. If a "logging" function calls another
37efac5ddb21fd91ed420c070ed07f375e78b3b9Lennart Poettering "logging" function, then it should not generate log messages, so
37efac5ddb21fd91ed420c070ed07f375e78b3b9Lennart Poettering that log messages are not generated twice for the same errors.
7348b3adb324614132cf376f478e883bd7de28f1Lennart Poettering- Avoid static variables, except for caches and very few other
e107ed185ef08945102834234a05ec51bb438685Lennart Poettering cases. Think about thread-safety! While most of our code is never
e107ed185ef08945102834234a05ec51bb438685Lennart Poettering used in threaded environments, at least the library code should make
81429136905a6204875174b60a179333b7f3c9e4Kay Sievers sure it works correctly in them. Instead of doing a lot of locking
81429136905a6204875174b60a179333b7f3c9e4Kay Sievers for that, we tend to prefer using TLS to do per-thread caching (which
e107ed185ef08945102834234a05ec51bb438685Lennart Poettering only works for small, fixed-size cache objects), or we disable
f598ac3e28b729dd0b1d0a881df3e16465687a2bLennart Poettering caching for any thread that is not the main thread. Use
11fb37f16ed99c1603c9d770b60ce4953b96a58dLennart Poettering is_main_thread() to detect whether the calling thread is the main
edb2935c5c5b95c42b8679086f60da5eafad74cbLennart Poettering- Command line option parsing:
edb2935c5c5b95c42b8679086f60da5eafad74cbLennart Poettering - Do not print full help() on error, be specific about the error.
769918ecd30c0f7ee6e87b9aa6226d956bd2f530Lennart Poettering - Do not print messages to stdout on error.
769918ecd30c0f7ee6e87b9aa6226d956bd2f530Lennart Poettering - Do not POSIX_ME_HARDER unless necessary, i.e. avoid "+" in option string.
769918ecd30c0f7ee6e87b9aa6226d956bd2f530Lennart Poettering- Do not write functions that clobber call-by-reference variables on
6a3f892a23db71544d0439355f96c44350dafa8fLennart Poettering failure. Use temporary variables for these cases and change the
2a781fc9bd33982c81e5ff75974a442a33d4f167Lennart Poettering passed in variables only on success.