docs: point out that locals should be defined at the top of a block of code

Although we have nothing in make syntax-check to enforce this, and
apparently there are places where it isn't the case (according to
Dan), we should discourage the practice of defining new variables in
the middle of a block of code.

https://www.redhat.com/archives/libvir-list/2020-July/msg00433.html

Signed-off-by: Laine Stump <laine@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>

diff --git a/docs/coding-style.rst b/docs/coding-style.rst
index 03b89c86e50aff7f3af4f098ce33d9fe77a966b1..9212a42a77e979e8425498304bbefea0c0c4dfd7 100644 (file)
--- a/docs/coding-style.rst
+++ b/docs/coding-style.rst
@@ -541,6 +541,44 @@ diligent about this, when you see a non-const pointer, you're
 guaranteed that it is used to modify the storage it points to, or
 it is aliased to another pointer that is.
 
+Defining Local Variables
+------------------------
+
+Always define local variables at the top of the block in which they
+are used (before any pure code). Although modern C compilers allow
+defining a local variable in the middle of a block of code, this
+practice can lead to bugs, and must be avoided in all libvirt
+code. As indicated in these examples, it is okay to initialize
+variables where they are defined, even if the initialization involves
+calling another function.
+
+::
+
+  GOOD:
+    int
+    bob(char *loblaw)
+    {
+        int x;
+        int y = lawBlog();
+        char *z = NULL;
+
+        x = y + 20;
+        ...
+    }
+
+  BAD:
+    int
+    bob(char *loblaw)
+    {
+        int x;
+        int y = lawBlog();
+
+        x = y + 20;
+
+        char *z = NULL; // <===
+        ...
+    }
+
 Attribute annotations
 ---------------------