2011-05-02 09:14:42 +00:00
|
|
|
Style guidelines
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
Indentation
|
|
|
|
|
-----------
|
|
|
|
|
Code must be indented using four spaces.
|
|
|
|
|
In vim, this can be accomplished using
|
|
|
|
|
|
|
|
|
|
set shiftwidth=4
|
|
|
|
|
set expandtab
|
|
|
|
|
|
|
|
|
|
Naming
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
|
global variables should be `$UPPERCASE`.
|
|
|
|
|
|
|
|
|
|
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?
|
|
|
|
|
|
|
|
|
|
functions should be lowercase+underscores: `do_this()`
|
2011-12-01 19:04:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Reporting to the user
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
There are some nifty messaging functions to use. They all come with
|
|
|
|
|
shortcuts that you can use during development or for temporary
|
|
|
|
|
messages. The long name is to be used for translatable strings.
|
|
|
|
|
|
|
|
|
|
They display formatted messages, using colors when available.
|
|
|
|
|
|
|
|
|
|
DEBUG=1 make the _verbose messages visible.
|
|
|
|
|
QUIET=1 suppresses all messages (but the _verbose messages if DEBUG=1).
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
_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.
|
|
|
|
|
|
|
|
|
|
_success (yes) You want to tell the user about a successful result.
|
|
|
|
|
|
|
|
|
|
All messaging function take a single "message" argument.
|
|
|
|
|
_failure takes an exit code as an optional second argument.
|
|
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
|
|
_verbose "Showing translatable debug message"
|
|
|
|
|
xxx "This is temporary debug"
|
|
|
|
|
_message "The program is doing something"
|
|
|
|
|
_message -n "Inline messages "
|
|
|
|
|
echo "are useful"
|
|
|
|
|
_success "All is fine"
|
|
|
|
|
_warning "Something's wrong"
|
|
|
|
|
_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
|
|
|
|
|
|
|
|
|
|
Will display something like:
|
|
|
|
|
|
|
|
|
|
tomb [D] Showing translatable debug message
|
|
|
|
|
tomb [D] This is temporary debug
|
|
|
|
|
tomb . The program is doing something
|
|
|
|
|
tomb > Inline messages are useful
|
|
|
|
|
tomb (*) All is fine
|
|
|
|
|
tomb [W] Something's wrong
|
|
|
|
|
tomb [E] Fatal error: exiting with default exit code 1
|
