X-Git-Url: https://gerrit.fd.io/r/gitweb?p=csit.git;a=blobdiff_plain;f=docs%2Fbash_code_style.rst;h=5a73d7b73613b46d976de76b48639250f8ff2230;hp=9db968f7d8c9d2c46d02dcfaab9c82eb275f9686;hb=694b418272e9d7670ac69d477ed731bb7445b65a;hpb=bf4685dcf156517f66fe68a825c768bd82a1a12b

diff --git a/docs/bash_code_style.rst b/docs/bash_code_style.rst
index 9db968f7d8..5a73d7b736 100644
--- a/docs/bash_code_style.rst
+++ b/docs/bash_code_style.rst
@@ -184,8 +184,7 @@ Bash options
 
     + "Near start" means "before any nontrivial code".
 
-    + Basically only copyright and long high-level comments are
-      RECOMMENDED to appear before.
+    + Basically only copyright is RECOMMENDED to appear before.
 
   + Also code MUST put the line near start of function bodies
     and subshell invocations.
@@ -235,7 +234,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
 ~~~~~~~~~