Bash functions style cleanup

+ Update rst documentation for bash style
 + Command substitution:
  + Clarify when to use backticks.
  + Recommend avoiding nested command substitution.
  + Do not recommend putting command substitution results into quotes.
 + Function definition content:
  + Move "set -exuo pipefail" after comment only blocks.
  + Other set flags allowed for functions with good reasons.
+ Apply the new recommendations.
 - Blank lines unified in code but no written recommendation in rst.
+ Add missing references to functions called, variables read or set.
 + Add TODOs to where lists would be long.
+ Minor improvements to function descriptions.
+ Make "if" expressions more python-like.
+ Add missing "|| die" (or "|| true") where spotted.
+ Downgrade DEFAULT_NIC to a local variable.
+ Add TODO to list reasons for blacklisted tags.

Change-Id: I05dce030a8c2cb1b3a242d8b977e8fe150d8ee20
Signed-off-by: Vratko Polak <vrpolak@cisco.com>

1 files changed, 21 insertions, 15 deletions

diff --git a/docs/bash_code_style.rst b/docs/bash_code_style.rst
index e5dbc9c06e..e955f72ab4 100644
--- a/docs/bash_code_style.rst
+++ b/docs/bash_code_style.rst
@@ -82,22 +82,24 @@ Safety
 
     + TODO: Consider giving examples both for good and bad usage.
 
-  + Command substitution on right hand side of assignment should be safe
+  + Command substitution on right hand side of assignment are safe
     without quotes.
 
-    + But still, quotes are RECOMMENDED, unless line length is a concern.
-
     + Note that command substitution limits the scope for quotes,
       so it is NOT REQUIRED to escape the quotes in deeper levels.
 
-    + TODO: Do we prefer backtics, or "dollar round-bracket"?
+    + Both backtics and "dollar round-bracket" provide command substitution.
+      The folowing rules are RECOMMENDED:
+
+      + For simple constructs, use "dollar round-bracket".
 
-      + Backticks are more readable, especially when there are
-        round brackets in the surrounding text.
+      + If there are round brackets in the surrounding text, use backticks,
+        as some editor highlighting logic can get confused.
 
-      + Backticks do not allow nested command substitution.
+      + Avoid nested command substitution.
 
-        + But we might want to avoid nested command substitution anyway?
+        + Put intermediate results into local variables,
+          use "|| die" on each step of command substitution.
 
   + Code SHOULD NOT be structured in a way where
     word splitting is intended.
@@ -541,21 +543,25 @@ Library documentation
 
 + Then SHALL be the function definitions, and inside:
 
-  + "set -exuo pipefail" again.
-
-  + Following that SHALL be the function documentation explaining API contract.
+  + The body SHALL sart with the function documentation explaining API contract.
     Similar to Robot [Documentation] or Python function-level docstring.
 
     + See below.
 
-  + Following that SHALL be varius TODOs, FIXMEs and code itself.
+  + Following that SHALL be various top-level TODOs and FIXMEs.
+
+    + TODO: Document (in an appropriate place) how TODOs differ from FIXMEs.
+
+  + "set -exuo pipefail" SHALL be the first executable line
+    in the function body, except functions which legitimely need
+    different flags. Those SHALL also start with appropriate "set" command(s).
+
+  + Lines containing code itself SHALL follow.
 
     + "Code itself" SHALL include comment lines
       explaining any non-obvious logic.
 
-    + TODO: Document (in an appropriate place) how TODOs differ from FIXMEs.
-
-  + There SHALL be two empty lines before next function definition.
+  + There SHALL be two empty lines between function definitions.
 
 More details on function documentation: