From 8d0e0ddda6501479eb69164687c83c1a7667b33a Mon Sep 17 00:00:00 2001 From: Jan Engelhardt Date: Sat, 28 Jun 2014 00:48:28 +0200 Subject: doc: grammatical corrections --- CODING_STYLE | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'CODING_STYLE') diff --git a/CODING_STYLE b/CODING_STYLE index 4ec5923d3d..cb8d96c4cb 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -10,14 +10,14 @@ - The destructors always unregister the object from the next bigger object, not the other way around -- To minimize strict aliasing violations we prefer unions over casting +- To minimize strict aliasing violations, we prefer unions over casting -- For robustness reasons destructors should be able to destruct +- For robustness reasons, destructors should be able to destruct half-initialized objects, too - Error codes are returned as negative Exxx. i.e. return -EINVAL. There - are some exceptions: for constructors it is OK to return NULL on - OOM. For lookup functions NULL is fine too for "not found". + are some exceptions: for constructors, it is OK to return NULL on + OOM. For lookup functions, NULL is fine too for "not found". Be strict with this. When you write a function that can fail due to more than one cause, it *really* should have "int" as return value @@ -30,7 +30,7 @@ program" code. (With one exception: it's OK to log with DEBUG level from any code, with the exception of maybe inner loops). -- Always check OOM. There's no excuse. In program code you can use +- Always check OOM. There's no excuse. In program code, you can use "log_oom()" for then printing a short message, but not in "library" code. - Do not issue NSS requests (that includes user name and host name @@ -123,19 +123,19 @@ backwards! - Think about the types you use. If a value cannot sensibly be - negative don't use "int", but use "unsigned". + negative, don't use "int", but use "unsigned". - Don't use types like "short". They *never* make sense. Use ints, longs, long longs, all in unsigned+signed fashion, and the fixed - size types uint32_t and so on, as well as size_t but nothing else. + size types uint32_t and so on, as well as size_t, but nothing else. - Public API calls (i.e. functions exported by our shared libraries) must be marked "_public_" and need to be prefixed with "sd_". No other functions should be prefixed like that. -- In public API calls you *must* validate all your input arguments for +- In public API calls, you *must* validate all your input arguments for programming error with assert_return() and return a sensible return - code. In all other calls it is recommended to check for programming + code. In all other calls, it is recommended to check for programming errors with a more brutal assert(). We are more forgiving to public users then for ourselves! Note that assert() and assert_return() really only should be used for detecting programming errors, not for @@ -153,16 +153,16 @@ on their own, "non-logging" function never log on their own and expect their callers to log. All functions in "library" code, i.e. in src/shared/ and suchlike must be "non-logging". Everytime a - "logging" function calls a "non-logging" function it should log + "logging" function calls a "non-logging" function, it should log about the resulting errors. If a "logging" function calls another "logging" function, then it should not generate log messages, so that log messages are not generated twice for the same errors. - Avoid static variables, except for caches and very few other cases. Think about thread-safety! While most of our code is never - used in threaded environments at least the library code should make + used in threaded environments, at least the library code should make sure it works correctly in them. Instead of doing a lot of locking - for that we tend to prefer using TLS to do per-thread caching (which + for that, we tend to prefer using TLS to do per-thread caching (which only works for small, fixed-size cache objects), or we disable caching for any thread that is not the main thread. Use is_main_thread() to detect whether the calling thread is the main -- cgit v1.2.3-54-g00ecf