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.
```
