tHACKING.txt - tomb - the crypto undertaker
 (HTM) git clone git://parazyd.org/tomb.git
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       tHACKING.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