CODING_STYLE revision 3fdbc8205885f117b7dea289b44217310663e731
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- 8ch indent, no tabs
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts- Don't break code lines too eagerly. We do *not* force line breaks at
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts 80ch, all of today's screens should be much larger than that. But
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts then again, don't overdo it, ~140ch should be enough really.
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts- Variables and functions *must* be static, unless they have a
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts prototype, and are supposed to be exported.
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts- structs in MixedCase (with exceptions, such as public API structs),
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts variables + functions in lower_case.
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts- The destructors always unregister the object from the next bigger
ccf9d4a5c6453fa9f8b839baeee25147865fbb7dJames Phillpotts object, not the other way around
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- To minimize strict aliasing violations, we prefer unions over casting
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- For robustness reasons, destructors should be able to destruct
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings half-initialized objects, too
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Error codes are returned as negative Exxx. i.e. return -EINVAL. There
be8ae89dc821957bb97b37f72b55e70677b19e61sachiko are some exceptions: for constructors, it is OK to return NULL on
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings OOM. For lookup functions, NULL is fine too for "not found".
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings Be strict with this. When you write a function that can fail due to
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings more than one cause, it *really* should have "int" as return value
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings for the error code.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not bother with error checking whether writing to stdout/stderr
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not log errors from "library" code, only do so from "main
1937848ad641fa32fce52f8570626a635cef6d30David Luna program" code. (With one exception: it is OK to log with DEBUG level
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings from any code, with the exception of maybe inner loops).
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Always check OOM. There is no excuse. In program code, you can use
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings "log_oom()" for then printing a short message, but not in "library" code.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not issue NSS requests (that includes user name and host name
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings lookups) from PID 1 as this might trigger deadlocks when those
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings lookups involve synchronously talking to services that we would need
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not synchronously talk to any other service from PID 1, due to
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings risk of deadlocks
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Avoid fixed-size string buffers, unless you really know the maximum
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings size and that maximum size is small. They are a source of errors,
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings since they possibly result in truncated strings. It is often nicer
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings to use dynamic memory, alloca() or VLAs. If you do allocate fixed-size
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings strings on the stack, then it is probably only OK if you either
1937848ad641fa32fce52f8570626a635cef6d30David Luna use a maximum size such as LINE_MAX, or count in detail the maximum
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings size a string can have. (DECIMAL_STR_MAX and DECIMAL_STR_WIDTH
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings macros are your friends for this!)
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings Or in other words, if you use "char buf[256]" then you are likely
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings doing something wrong!
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Stay uniform. For example, always use "usec_t" for time
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings values. Do not usec mix msec, and usec and whatnot.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Make use of _cleanup_free_ and friends. It makes your code much
ef95957ed92d5c54e70e1a032e4e379dd930b46aDavid Luna nicer to read!
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Be exceptionally careful when formatting and parsing floating point
be8ae89dc821957bb97b37f72b55e70677b19e61sachiko numbers. Their syntax is locale dependent (i.e. "5.000" in en_US is
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings generally understood as 5, while on de_DE as 5000.).
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Try to use this:
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings instead of this:
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings But it is OK if you do not.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not write "foo ()", write "foo()".
ef95957ed92d5c54e70e1a032e4e379dd930b46aDavid Luna- Please use streq() and strneq() instead of strcmp(), strncmp() where applicable.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Please do not allocate variables on the stack in the middle of code,
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings even if C99 allows it. Wrong:
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Unless you allocate an array, "double" is always the better choice
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings than "float". Processors speak "double" natively anyway, so this is
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings no speed benefit, and on calls like printf() "float"s get promoted
71dbce1f4a6beaa47887299ee08c1c36d65d3183David Luna to "double"s anyway, so there is no point.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not invoke functions when you allocate variables on the stack. Wrong:
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings int a = foobar();
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings uint64_t x = 7;
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings uint64_t x = 7;
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings a = foobar();
71dbce1f4a6beaa47887299ee08c1c36d65d3183David Luna- Use "goto" for cleaning up, and only use it for that. i.e. you may
71dbce1f4a6beaa47887299ee08c1c36d65d3183David Luna only jump to the end of a function, and little else. Never jump
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Think about the types you use. If a value cannot sensibly be
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings negative, do not use "int", but use "unsigned".
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Do not use types like "short". They *never* make sense. Use ints,
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings longs, long longs, all in unsigned+signed fashion, and the fixed
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings size types uint32_t and so on, as well as size_t, but nothing else.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Public API calls (i.e. functions exported by our shared libraries)
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings must be marked "_public_" and need to be prefixed with "sd_". No
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings other functions should be prefixed like that.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- In public API calls, you *must* validate all your input arguments for
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings programming error with assert_return() and return a sensible return
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings code. In all other calls, it is recommended to check for programming
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings errors with a more brutal assert(). We are more forgiving to public
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings users then for ourselves! Note that assert() and assert_return()
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings really only should be used for detecting programming errors, not for
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings runtime errors. assert() and assert_return() by usage of _likely_()
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings inform the compiler that he should not expect these checks to fail,
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings and they inform fellow programmers about the expected validity and
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings range of parameters.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Never use strtol(), atoi() and similar calls. Use safe_atoli(),
71dbce1f4a6beaa47887299ee08c1c36d65d3183David Luna safe_atou32() and suchlike instead. They are much nicer to use in
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings most cases and correctly check for parsing errors.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- For every function you add, think about whether it is a "logging"
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings function or a "non-logging" function. "Logging" functions do logging
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings on their own, "non-logging" function never log on their own and
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings expect their callers to log. All functions in "library" code,
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings i.e. in src/shared/ and suchlike must be "non-logging". Everytime a
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings "logging" function calls a "non-logging" function, it should log
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings about the resulting errors. If a "logging" function calls another
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings "logging" function, then it should not generate log messages, so
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings that log messages are not generated twice for the same errors.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Avoid static variables, except for caches and very few other
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings cases. Think about thread-safety! While most of our code is never
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings used in threaded environments, at least the library code should make
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings sure it works correctly in them. Instead of doing a lot of locking
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings for that, we tend to prefer using TLS to do per-thread caching (which
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings only works for small, fixed-size cache objects), or we disable
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings caching for any thread that is not the main thread. Use
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings is_main_thread() to detect whether the calling thread is the main
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings- Option parsing:
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings - Do not print full help() on error, be specific about the error.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings - Do not print messages to stdout on error.
449854c2a07b50ea64d9d6a8b03d18d4afeeee43Ken Stubbings - Do not POSIX_ME_HARDER unless necessary, i.e. avoid "+" in option string.