docs: update coding style a bit

Say that r should be declared at the top of the function.

Don't say that fixed buffers result in truncation, right after saying that they
must only be used if size is known.

Adjust order of examples to be consistent.

1 files changed, 20 insertions, 13 deletions

diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index 847ec40d81..09b74d35d8 100644
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -143,38 +143,46 @@ layout: default
 
 ## Using C Constructs
 
-- Preferably allocate local variables on the top of the block:
+- Allocate local variables where it makes sense: at the top of the block, or at
+  the point where they can be initialized. `r` is typically used for a local
+  state variable, but should almost always be declared at the top of the
+  function.
 
   ```c
   {
-          int a, b;
+          uint64_t a, b;
+          int r;
 
-          a = 5;
-          b = a;
+          a = frobnicate();
+          b = a + 5;
+
+          r = do_something();
+          if (r < 0)
+                  …
   }
   ```
 
-- Do not mix function invocations with variable definitions in one line. Wrong:
+- Do not mix function invocations with variable definitions in one line.
 
   ```c
   {
-          int a = foobar();
           uint64_t x = 7;
+          int a;
+
+          a = foobar();
   }
   ```
 
-  Right:
+  instead of:
 
   ```c
   {
-          int a;
+          int a = foobar();
           uint64_t x = 7;
-
-          a = foobar();
   }
   ```
 
-- Use `goto` for cleaning up, and only use it for that. i.e. you may only jump
+- Use `goto` for cleaning up, and only use it for that. I.e. you may only jump
   to the end of a function, and little else. Never jump backwards!
 
 - To minimize strict aliasing violations, we prefer unions over casting.
@@ -347,8 +355,7 @@ layout: default
   `log_oom()` for then printing a short message, but not in "library" code.
 
 - 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,
+  that maximum size is small. It is often nicer to use dynamic memory,
   `alloca()` or VLAs. If you do allocate fixed-size 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