aboutsummaryrefslogtreecommitdiffstats
path: root/docs/bash_code_style.rst
diff options
context:
space:
mode:
authorVratko Polak <vrpolak@cisco.com>2019-07-10 13:59:50 +0200
committerPeter Mikus <pmikus@cisco.com>2019-07-10 14:23:48 +0000
commit36d56bdb7f9f394047e2df3f29bf47db877b649c (patch)
treede01e08334759f2f41b30dabcbd179b94015b0e0 /docs/bash_code_style.rst
parente45404bf7b8cbdb10adf85815c2e005134e463ad (diff)
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>
Diffstat (limited to 'docs/bash_code_style.rst')
-rw-r--r--docs/bash_code_style.rst36
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: