t[cleanup] Improve style guide - tomb - the crypto undertaker
(HTM) git clone git://parazyd.org/tomb.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 64c20d95f28cc7ce0bfdc0a21a34988fe18b24b7
(DIR) parent 9539d0cc4bac3d4c6a7352202b2df788c6b905c8
(HTM) Author: hellekin <hellekin@cepheide.org>
Date: Wed, 22 Oct 2014 18:13:14 -0300
t[cleanup] Improve style guide
Diffstat:
M doc/HACKING.txt | 80 ++++++++++++++++++++++++++-----
1 file changed, 68 insertions(+), 12 deletions(-)
---
(DIR) diff --git a/doc/HACKING.txt b/doc/HACKING.txt
t@@ -3,6 +3,7 @@ Style guidelines
Indentation
-----------
+
Code must be indented using four spaces.
In vim, this can be accomplished using
t@@ -12,13 +13,64 @@ In vim, this can be accomplished using
Naming
------
-global variables should be `$UPPERCASE`.
+Short version: $GLOBAL, $local, func_name()
+
+Variables must be declared and scoped.
+
+GLOBAL_VARIABLES # are uppercase unless there's a good reason not to.
+ # (e.g., path as a special meaning in Zsh)
+
+local samplevar # are lowercase and scoped to the function # name
+ # should be readable. Do not make unnecessary
+ # shortcuts that would impede others to read fluidly
+
+# Please comment your functions before coding them: it helps
+# clear the mind on the objective. If it does too much, you
+# probably want to split it. Any reusable code should be
+# isolated.
+any_function() {}
+
+_internals() {} # Prepend an _ if the function is clearly internal,
+ # that is, if it's only called within the scope of
+ # another function.
+
+
+Sample code:
+
+# Sample public command.
+#
+# It shows developers how to write readable code.
+# Returns 0 on success, or fails
+public_command() {
+ local tombpath="$1" # First argument is the path to the tomb
+ local orientation="${2:-South}" # Second optional argument
+ local something is happening
+
+ [[ -z $tombpath ]] && {
+ _failure "Usage public_command tombpath [orientation=South]" }
+
+ case $orientation in
+ (South|North|East|West) break;;
+ (*)
+ _failure "orientation must be one of South, North, East, or West."
+ ;;
+ esac
-local variables should be `$lowercase`, best if it can be written without underscores.
-If you feel the need to name a variable `$longdescriptionofwhatthisisusefulfor`,
-then you're allowed to use underscores. But do you really need?
+ _check_swap # Ensure the available memory is safe
+ _plot $tombpath # Set TOMB{PATH,DIR,FILE,NAME}
-functions should be lowercase+underscores: `do_this()`
+ for is in $TOMBLOOPDEVS; do
+ [[ -k $is ]] && {
+ happening+="$is "
+ } || {
+ something+="$is "
+ }
+ done
+
+ _message "You gotta sort your bones."
+
+ return 0
+}
Reporting to the user
t@@ -37,20 +89,22 @@ Here is the deal:
Name (Shortcut) Return When to use
=================================================================================
-_failure (die) exit 1 You want to exit the program with a fatal error.
- You may pass a different exit code as second argument.
-
-_warning (no) You want to inform the user about an error condition.
+_verbose (xxx) You need to check the current state of the program.
_message (say) You want to tell the user about what's going on.
You can pass -n (shortcut: act) for inline messages.
-_verbose (xxx) You need to check the current state of the program.
+_warning (no) You want to inform the user about an error condition.
_success (yes) You want to tell the user about a successful result.
+_failure (die) exit 1 You want to exit the program with a fatal error.
+ You may pass a different exit code as exitval.
+
All messaging function take a single "message" argument.
-_failure takes an exit code as an optional second argument.
+_failure takes an exit code as an optional exitval environment variable.
+
+Additionally you can use _print to pass translatable string without decoration.
Examples:
t@@ -61,9 +115,10 @@ Examples:
echo "are useful"
_success "All is fine"
_warning "Something's wrong"
+ _print "Did I really say that?"
_failure "Fatal error: exiting with default exit code 1"
_message "This is not reached, nor the next 'die' command"
- die "I am Jack's dead corpse." 127
+ exitval=127 die "I am Jack's dead corpse."
Will display something like:
t@@ -73,4 +128,5 @@ Will display something like:
tomb > Inline messages are useful
tomb (*) All is fine
tomb [W] Something's wrong
+ Did I really say that?
tomb [E] Fatal error: exiting with default exit code 1