chiark / gitweb /
doc: grammatical corrections
[elogind.git] / CODING_STYLE
index 4ec5923..cb8d96c 100644 (file)
 - 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
   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
   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