tomb

the crypto undertaker
git clone git://parazyd.org/tomb.git
Log | Files | Refs | README | LICENSE

HACKING.txt (4055B)

      1 Style guidelines
      2 ===============
      3 
      4 Indentation
      5 -----------
      6 
      7 Code must be indented using four spaces.
      8 In vim, this can be accomplished using
      9 
     10 	set shiftwidth=4
     11 	set expandtab
     12 
     13 Naming
     14 ------
     15 
     16 Short version: $GLOBAL, $local, func_name()
     17 
     18 Variables must be declared and scoped.
     19 
     20 GLOBAL_VARIABLES # are uppercase unless there's a good reason not to.
     21                  # (e.g., path as a special meaning in Zsh)
     22 
     23 local samplevar  # are lowercase and scoped to the function # name
     24                  # should be readable.  Do not make unnecessary
     25                  # shortcuts that would impede others to read fluidly
     26 
     27 # Please comment your functions before coding them: it helps 
     28 # clear the mind on the objective.  If it does too much, you
     29 # probably want to split it.  Any reusable code should be
     30 # isolated.
     31 any_function() {}
     32 
     33 _internals() {}  # Prepend an _ if the function is clearly internal,
     34                  # that is, if it's only called within the scope of
     35                  # another function.
     36 
     37 
     38 Sample code:
     39 
     40 # Sample public command.
     41 #
     42 # It shows developers how to write readable code.
     43 # Returns 0 on success, or fails 
     44 public_command() {
     45     local tombpath="$1"             # First argument is the path to the tomb
     46     local orientation="${2:-South}" # Second optional argument
     47     local something is happening
     48 
     49     [[ -z $tombpath ]] && {
     50         _failure "Usage public_command tombpath [orientation=South]" }
     51 
     52     case $orientation in
     53         (South|North|East|West) break;;
     54         (*)
     55             _failure "orientation must be one of South, North, East, or West."
     56             ;;
     57     esac
     58 
     59     _check_swap     # Ensure the available memory is safe
     60     _plot $tombpath # Set TOMB{PATH,DIR,FILE,NAME}
     61 
     62     for is in $TOMBLOOPDEVS; do
     63         [[ -k $is ]] && {
     64             happening+="$is "
     65         } || {
     66             something+="$is "
     67         }
     68     done
     69 
     70     _message "You gotta sort your bones."
     71 
     72     return 0
     73 }
     74 
     75 
     76 Reporting to the user
     77 ---------------------
     78 
     79 There are some nifty messaging functions to use. They all come with
     80 shortcuts that you can use during development or for temporary
     81 messages. The long name is to be used for translatable strings.
     82 
     83 They display formatted messages, using colors when available.
     84 
     85 DEBUG=1 make the _verbose messages visible.
     86 QUIET=1 suppresses all messages (but the _verbose messages if DEBUG=1).
     87 
     88 Here is the deal:
     89 
     90 Name (Shortcut)  Return    When to use
     91 =================================================================================
     92 _verbose (xxx)             You need to check the current state of the program.
     93 
     94 _message (say)             You want to tell the user about what's going on.
     95                            You can pass -n (shortcut: act) for inline messages.
     96 
     97 _warning (no)              You want to inform the user about an error condition.
     98 
     99 _success (yes)             You want to tell the user about a successful result.
    100 
    101 _failure (die)   exit 1    You want to exit the program with a fatal error.
    102                            You may pass a different exit code as exitval.
    103 
    104 All messaging function take a single "message" argument.
    105 _failure takes an exit code as an optional exitval environment variable.
    106 
    107 Additionally you can use _print to pass translatable string without decoration.
    108 
    109 Examples:
    110 
    111     _verbose "Showing translatable debug message"
    112          xxx "This is temporary debug"
    113     _message "The program is doing something"
    114     _message -n "Inline messages "
    115     echo "are useful"
    116     _success "All is fine"
    117     _warning "Something's wrong"
    118     _print   "Did I really say that?"
    119     _failure "Fatal error: exiting with default exit code 1"
    120     _message "This is not reached, nor the next 'die' command"
    121     exitval=127 die "I am Jack's dead corpse."
    122 
    123 Will display something like:
    124 
    125     tomb [D] Showing translatable debug message
    126     tomb [D] This is temporary debug
    127     tomb  .  The program is doing something
    128     tomb  >  Inline messages are useful
    129     tomb (*) All is fine
    130     tomb [W] Something's wrong
    131     Did I really say that?
    132     tomb [E] Fatal error: exiting with default exit code 1