[Savannah-cvs] [727] style guide, be clearer

[iank]

Revision: 727
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=727
Author:   iank
Date:     2023-12-14 17:31:20 -0500 (Thu, 14 Dec 2023)
Log Message:
-----------
style guide, be clearer

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-14 16:32:27 UTC (rev 
726)
+++ trunk/sviki/fsf/bash-style-guide.mdwn       2023-12-14 22:31:20 UTC (rev 
727)
@@ -143,8 +143,12 @@
 # Documentation
 
 Add comments describing functions that are not short and
-obvious. Document any arguments, global variables used, and any nonzero 
returns. See the <https://savannah.nongnu.org/git/?group=bash-bear-trap> for 
example.
+obvious.
 
+Document function arguments. Preferably document global variables used
+and nonzero returns. See the
+<https://savannah.nongnu.org/git/?group=bash-bear-trap> for example.
+
 Comment any tricky or important parts of code.
 
 Use TODO comments, eg:
@@ -153,6 +157,13 @@
 # TODO iank: add x functionality
 ```
 
+Document whenever a script is not idempotent. Try to make scripts be as
+idempotent as feasible. Idempotent means running the same script twice
+results in the same state, either repeating some steps or skipping steps
+that were already done, and it handles the case of a previous run which
+exited mid-way through.
+
+
 # Code style
 
 Indent 2 spaces.
@@ -200,8 +211,7 @@
 
 # Error handling
 
-You should pick one of the following options (each subheading is an
-option) and use it consistently throughout your script.
+There are 2 options: automatic and manual. Pick one and use it consistently 
throughout your script.
 
 ## Automatically exit on failed command:
 
@@ -342,6 +352,10 @@
 Explicit handling should
 be done for almost all commands not builtin to BASH.
 
+Add this to the top of your script. It is like automatic exit on error,
+but just prints when a command failed. It will help identify if your
+manual error checking was incomplete.
+
 ```
 set -E -o pipefail
 trap 'echo "$0:$LINENO:error: \"$BASH_COMMAND\" returned $?" >&2' ERR
@@ -369,11 +383,6 @@
 
 # Good practices
 
-Make scripts be as idempotent as feasible. For example, a script to
-create a vm. If you run it twice, the 2nd time it should just succeed
-and say "vm already exists." `mv` is an enemy of idempotency, try to
-avoid or be thoughtful in using it.
-
 Make variables set at the beginning of a script constant when possible.
 
 ```