From 8e5edf8d42d3c441e4b09aa1dbbaf2cb605c1328 Mon Sep 17 00:00:00 2001 From: Jan Engelhardt Date: Sat, 28 Jun 2014 00:50:28 +0200 Subject: [PATCH] doc: use expanded forms for written style --- CODING_STYLE | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/CODING_STYLE b/CODING_STYLE index e19294412..e22c1edb1 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -23,14 +23,14 @@ more than one cause, it *really* should have "int" as return value for the error code. -- Don't bother with error checking whether writing to stdout/stderr +- Do not bother with error checking whether writing to stdout/stderr worked. - Do not log errors from "library" code, only do so from "main - program" code. (With one exception: it's OK to log with DEBUG level + program" code. (With one exception: it is 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 is 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 @@ -38,14 +38,14 @@ lookups involve synchronously talking to services that we would need to start up -- Don't synchronously talk to any other service from PID 1, due to +- Do not synchronously talk to any other service from PID 1, due to risk of deadlocks - Avoid fixed-size string buffers, unless you really know the maximum size and that maximum size is small. They are a source of errors, since they possibly result in truncated strings. It is often nicer to use dynamic memory, alloca() or VLAs. If you do allocate fixed-size - strings on the stack, then it's probably only OK if you either + strings on the stack, then it is probably only OK if you either use a maximum size such as LINE_MAX, or count in detail the maximum size a string can have. (DECIMAL_STR_MAX and DECIMAL_STR_WIDTH macros are your friends for this!) @@ -54,7 +54,7 @@ doing something wrong! - Stay uniform. For example, always use "usec_t" for time - values. Don't usec mix msec, and usec and whatnot. + values. Do not usec mix msec, and usec and whatnot. - Make use of _cleanup_free_ and friends. It makes your code much nicer to read! @@ -74,9 +74,9 @@ { } - But it's OK if you don't. + But it is OK if you do not. -- Don't write "foo ()", write "foo()". +- Do not write "foo ()", write "foo()". - Please use streq() and strneq() instead of strcmp(), strncmp() where applicable. @@ -102,7 +102,7 @@ no speed benefit, and on calls like printf() "float"s get promoted to "double"s anyway, so there is no point. -- Don't invoke functions when you allocate variables on the stack. Wrong: +- Do not invoke functions when you allocate variables on the stack. Wrong: { int a = foobar(); @@ -123,9 +123,9 @@ backwards! - Think about the types you use. If a value cannot sensibly be - negative, don't use "int", but use "unsigned". + negative, do not use "int", but use "unsigned". -- Don't use types like "short". They *never* make sense. Use ints, +- Do not 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. @@ -140,7 +140,7 @@ users then for ourselves! Note that assert() and assert_return() really only should be used for detecting programming errors, not for runtime errors. assert() and assert_return() by usage of _likely_() - inform the compiler that he shouldn't expect these checks to fail, + inform the compiler that he should not expect these checks to fail, and they inform fellow programmers about the expected validity and range of parameters. -- 2.30.2