[Savannah-cvs] [718] style guide: make a few things make more sense

[iank]

Revision: 718
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=718
Author:   iank
Date:     2023-12-13 17:19:32 -0500 (Wed, 13 Dec 2023)
Log Message:
-----------
style guide: make a few things make more sense

Modified Paths:
--------------
    trunk/sviki/fsf/bash-style-guide.mdwn

Modified: trunk/sviki/fsf/bash-style-guide.mdwn
===================================================================
--- trunk/sviki/fsf/bash-style-guide.mdwn       2023-12-13 21:52:51 UTC (rev 
717)
+++ trunk/sviki/fsf/bash-style-guide.mdwn       2023-12-13 22:19:32 UTC (rev 
718)
@@ -142,7 +142,7 @@
 mapfile -t array <<<"$var"
 ```
 
-# Misc
+# Documentation
 
 Add comments describing functions that are not short and
 obvious. Document any arguments, global variables used, return value
@@ -157,6 +157,8 @@
 # TODO iank: add x functionality
 ```
 
+# Code style
+
 Indent 2 spaces.
 
 Try to wrap lines longer than ~80 chars. Use \ followed by newline where 
appropriate.
@@ -170,14 +172,14 @@
 END
 ```
 
-Put then and do on the same line as the condition:
+Use one line for `if ..;then` and `for ..;do` :
 
 ```
 if x; then
-  :
+  true
 fi
 for x; do
-  :
+  echo 'here $x is $1, then $2, up until $# - 1'
 done
 ```
 
@@ -187,42 +189,19 @@
 separates words. Declare constants and environment variables at the top
 of the file when possible.
 
-```
-# Constant
-readonly conf_dir=/some/path
-
-# Constant and environment
-declare -xr conf_dir=/some/path
-
-# A constant set based on condition needs to be set readonly after it's set.
-verbose=false
-if \[[ $1 ]]; then
-  verbose=true
-fi
-readonly verbose
-```
-
-Use `local` to properly scope variables as "function-local". This adds
-readability and avoids errors from using variables in unintended
-scopes. eg: `local y=5`
-
 Never quote literal integers.
 
 Prefer single-quoting strings that have no substitution (things that
 start with `$`).
 
-Non-command options or path names can be optionally quoted, eg: `x='oo'`.
+Command arguments and variable assignment can be optionally quoted, eg: 
`x='oo'`.
 
-
 Functions:
 
 Put all functions together near the top of the file after includes,
 constants, and `set` statements.
 
-Always use `return 0`, never `return`, because you can return nonzero
-by accident otherwise.
 
-
 # Error handling
 
 You should pick one of the following options (each subheading is an
@@ -383,8 +362,34 @@
 `${PIPESTATUS[@]}`.
 
 
-# Misc
+# Good practices
 
+Make variables set at the beginning of a script constant when possible.
+
+```
+# Constant
+readonly conf_dir=/some/path
+
+# Constant and environment
+declare -xr conf_dir=/some/path
+
+# A constant set based on condition needs to be set readonly after it's set.
+verbose=false
+if \[[ $1 ]]; then
+  verbose=true
+fi
+readonly verbose
+```
+
+Use `local` to properly scope variables as "function-local". This adds
+readability and avoids errors from using variables in unintended
+scopes. eg: `local y=5`
+
+
+Always use `return 0`, never `return`, because you can return nonzero
+by accident otherwise.
+
+
 Prefer the use of built-ins such as the Parameter Expansion functions
 (see `info '(bash)Shell Parameter Expansion'`) as they are more robust.