aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-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: