aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorVratko Polak <vrpolak@cisco.com>2019-02-18 14:29:06 +0100
committerPeter Mikus <pmikus@cisco.com>2019-02-18 16:25:40 +0000
commitd4158fdb3d3e4bca24cd299e63a97180a2544460 (patch)
tree3717f21e66b5b2c182ca4dcf6d482d462eacfa5e /docs
parent15e95017f280341f8ca463bab5645bbb318ac069 (diff)
Bash style: Explain some rules for entry and libs
Change-Id: I694ef0c45dfa342651f078d13cc0f7eaaeff82e9 Signed-off-by: Vratko Polak <vrpolak@cisco.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/bash_code_style.rst34
1 files changed, 33 insertions, 1 deletions
diff --git a/docs/bash_code_style.rst b/docs/bash_code_style.rst
index 9db968f7d8..3af2bb7ba6 100644
--- a/docs/bash_code_style.rst
+++ b/docs/bash_code_style.rst
@@ -235,7 +235,39 @@ here are some pros and cons:
+ This allows code blocks to support optional arguments.
-TODO: Translate the "function way" into list of rules.
++ Rules:
+
+ + Library files MUST be only "source"d. For example if "tox" calls a script,
+ it is an entry script.
+
+ + Library files (upon sourcing) MUST minimize size effect.
+
+ + The only permitted side effects MUST by directly related to:
+
+ + Defining functions (without executing them).
+
+ + Sourcing sub-library files.
+
+ + If a bash script indirectly call another bash script,
+ it is not a "source" operation, variables are not shared,
+ so the called script MUST be considered an entry script,
+ even if it implements logic fitting into a single function.
+
+ + Entry scripts SHOULD avoid duplicating any logic.
+
+ + Clear duplicated blocks MUST be moved into libraries as functions.
+
+ + Blocks with low amount of duplication MAY remain in entry scripts.
+
+ + Usual motives for not creating functions are:
+
+ + The extracted function would have too much logic for processing
+ arguments (instead of hardcoding values as in entry script).
+
+ + The arguments needed would be too verbose.
+
+ + And using "set +x" would take too much vertical space
+ (when compared to entry script implementation).
Variables
~~~~~~~~~