shell_coding_conventions.en.md

Shell Language

The shell language for any shell scripts is the bourne shell language. An adequate technical manual to the (posix) shell seems to be http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html.

Basic Format

The basic format is that all lines are indented by TABs (4 spaces!), and continuation lines (which in the shell end with "\") are indented by an equivalent number of TABs and then an additional two spaces, e.g.

    cp foo bar
    cp some_realllllllllllllllly_realllllllllllllly_long_path \
      to_another_really_long_path_with_er-ror

If, For, and While

The sh token equivalent to the C "{" should appear on the same line, separated by a ";", as in:

    if [ "$x" = hello ]; then
        echo $x
    fi

    for i in 1 2 3; do
        echo $i
    done

    i=0
    while [ $i -le 20 ]; do
        echo $i
        i=$(($i + 1))
    done

Test Built-in

DO NOT use the test built-in. Instead, use the [ builtin.

So, instead of

    if test $1 -gt 0; then

use:

    if [ "$1" -gt 0 ]; then

Single-line conditional statements

It is permissible to use && and || to construct shorthand for an "if" statement in the case where the if statement has a single consequent line:

    [ "$1" -eq 0 ] && exit 0

instead of the longer:

    if [ $1 -eq 0 ]; then
        exit 0
    fi

DO NOT combine && with { }, as in:

    [ "$1" -eq 0 ] && {
        do something
        do something else
    }

Use a complete "if-then-fi" construct for this instead.

Remark by kriegaex (2012-01-21): Nobody ever asked me for my opinion, yet I get bugged by one or two people whenever I do this:

    [ $foo -eq 0 ] \
        && echo "tea"
        || echo "coffee"

    [ $foo -eq 0 ] && [ "$bar" != "oops" ] \
        && command1 | grep "xxx" \
        || command2

I will continue to use this as a shorthand for if-else as long as there are no nested && or || constructs or brackets involved. Whenever I use it, I indent it cleanly and use it exactly analogous to if-else, so it is always condition && true-case || false-case, never anything more complicated. I am even putting && or || to the beginning of the indented lines on purpose so as to document the condition for executing the statements.

I also think that this

    while condition; do
        command1 &&
        command2 &&
        command3 &&
        command4 &&
        echo "result"
    done

should be permitted because it is more readable than (and still trivial enough)

    while condition; do
        command1 || continue
        command2 || continue
        command3 || continue
        command4 || continue
        echo "result"
    done

There is a reason why && and || were invented, and I believe that this case does not look obfuscated in any way.

Infinite Loops

This should be discussed: The original solaris sh style guide says not to use "true", as this is normally not a shell builtin, and instead use :, which also evaluates to true. In the busybox sh used with freetz, "true" is also a shell builtin, and as it is more readable, it should be prefered over ":":

    while true; do
        echo infinite loop
    done

Exit Status and If/While Statements

Recall that "if" and "while" operate on the exit status of the statement to be executed. In the shell, zero (0) means true and non-zero means false. The exit status of the last command which was executed is available in the $? variable. When using "if" and "while", it is typically not necessary to use $? explicitly, as in:

    grep foo /etc/passwd >/dev/null 2>&1
    if [ $? -eq 0 ]; then
        echo found
    fi

Instead, you can more concisely write:

    if grep foo /etc/passwd >/dev/null 2>&1; then
        echo found
    fi

Or, when appropriate:

    grep foo /etc/passwd >/dev/null 2>&1 && echo found

Variable References

Variable references begin with $ and *may* have their name enclosed in {}'s. They should only be used when required.

Braces are required around variable names in two specific cases:

(1) when you are forming the string concatenation of your variable with another string:

    [ "$install" = yes ] && root="/a/" || root="/"
    hosts=${root}etc/inet/hosts

and (2) when you are using one of the various substitution/assignment operators:

    echo ${BASEDIR:-/a}

Variable Naming

Shell variables should usually be all lower case, except for a few exceptions, where CAPTITAL letters are to be used:

(1) variables that are exported into the environment:

    BASEDIR=/a; export BASEDIR

(2) variables that are used like constants

    TMP=/var/tmp
    FLASH=$TMP/flash

This helps your reader immediately understand the implication of modifying a given variable (i.e. whether it will be inherited by child processes).

Quoting

Quick review of the quoting basics:

single quotes ('') mean quote but do not expand variable or backquote substitutions.
Double quotes ("") mean quote but allow expansion.
Backquotes () mean execute the command and substitute its standard output
(note: stderr is unchanged and may "leak" through unless properly redirected)''

Use quotes wherever they could be necessary, even when knowing that for example a variable does only expand to one word at the moment. This can save us from possible side effects of later code changes.

But please do not unnecessarily quote everything. Literals should usually not be quoted:

    [ -r /path/to/some/file ] && rm /path/to/some/file

The usage of backquotes (``) is discouraged in favor of the "new" form $().

Variable Assignments

Variable assignments should not be quoted if unnecessary:

    variable=yes
    variable=$(ls)
    variable="some text"

Testing for (Non-)Empty Strings

DO NOT test for non-/empty strings by comparing to "" or . ALWAYS use the test operators -n (non-zero-length string) and -z (zero-length string):

    if [ -z "$foo" ]; then
        echo 'you forgot to set $foo'
    fi

    if [ -n "$BASEDIR" ]; then
        echo "\$BASEDIR is set to $BASEDIR"
    fi

Commenting

As usual, comments are mainly intended for maintainers of the files, that means probably not you but someone else. Comments should describe why something is done the way it is done, or explain complicated statements that are not obvious. A summary for a whole block of code or the synopsis of a function are also useful. Comments should not explain what a simple line of code does, as it should be assumed that the reader is familiar with the language.

Shell comments are preceded by the '#' character. Both single and multi-line comments are to be placed at line begin. Use an extra '#' above and below the comment in the case of multi-line comments:

    # Copy foo to bar (this is an example of a useless comment, the purpose of cp should be known).
    cp foo bar

    #
    # Modify the permissions on bar. (This is obvious from the code and not necessary.)
    # We need to set them to root/sys in order to match the package prototype.
    # (This information is useful because it is not contained in the code.)
    #
    chown root bar
    chgrp sys bar

Pathnames

It is always a good idea to be careful about $PATH settings and pathnames when writing shell scripts. This allows them to function correctly even when the user invoking your script has some strange $PATH set in their environment.

There are two acceptable ways to do this:

(1) make all command references in your script use explicit pathnames:

    /usr/bin/chown root bar
    /usr/bin/chgrp sys bar

or (2) explicitly reset $PATH in your script:

    PATH=/usr/bin; export PATH

    chown root bar
    chgrp sys bar

DO NOT use a mixture of (1) and (2) in the same script. Pick one method and use it consistently.

Interpreter Magic

The proper interpreter magic (aka shebang) for shell script is:

    #!/bin/sh