Merge pull request #6693 from qlyoung/doc-value-initialization-practices

Document value initialization practices

2 files changed, 26 insertions, 2 deletions

diff --git a/doc/developer/lua.rst b/doc/developer/lua.rst
index 23eb35fc58..3315c31ad7 100644
--- a/doc/developer/lua.rst
+++ b/doc/developer/lua.rst
@@ -53,7 +53,7 @@ follow these steps:
          zlog_debug(string.format("afi: %d: %s %d ifdx: %d aspath: %s localpref: %d",
                     prefix.family, prefix.route, nexthop.metric,
                     nexthop.ifindex, nexthop.aspath, nexthop.localpref))
-    
+
          nexthop.metric =  33
          nexthop.localpref = 13
          return 3
diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst
index ef25982077..f345464a35 100644
--- a/doc/developer/workflow.rst
+++ b/doc/developer/workflow.rst
@@ -276,7 +276,7 @@ Pre-submission Checklist
 - In the case of a major new feature or other significant change, document
   plans for continued maintenance of the feature.  In addition it is a
   requirement that automated testing must be written that exercises
-  the new feature within our existing CI infrastructure.  Also the 
+  the new feature within our existing CI infrastructure.  Also the
   addition of automated testing to cover any pull request is encouraged.
 
 .. _signing-off:
@@ -573,6 +573,30 @@ following requirements have achieved consensus:
   constant in these cases.  (Rationale:  changing a buffer to another size
   constant may leave the write operations on a now-incorrect size limit.)
 
+- For stack allocated structs and arrays that should be zero initialized,
+  prefer initializer expressions over ``memset()`` wherever possible. This
+  helps prevent ``memset()`` calls being missed in branches, and eliminates the
+  error class of an incorrect ``size`` argument to ``memset()``.
+
+  For example, instead of:
+
+  .. code-block:: c
+
+     struct foo mystruct;
+     ...
+     memset(&mystruct, 0x00, sizeof(struct foo));
+
+  Prefer:
+
+  .. code-block:: c
+
+     struct foo mystruct = {};
+
+- Do not zero initialize stack allocated values that must be initialized with a
+  nonzero value in order to be used. This way the compiler and memory checking
+  tools can catch uninitialized value use that would otherwise be suppressed by
+  the (incorrect) zero initialization.
+
 Other than these specific rules, coding practices from the Linux kernel as
 well as CERT or MISRA C guidelines may provide useful input on safe C code.
 However, these rules are not applied as-is;  some of them expressly collide