11.1. What's That Do?

Six months ago you coded up a 100 line shell script. It made perfect sense then, but now you look at it and wonder, "Just what does that do?" This is a common pitfall among programmers—especially those writing in a shell language. Unfortunately, shells have developed with more than their fair share of obscure punctuation. This is a blessing for keeping typing to a minimum but doesn't help readability. It's important to make your code as readable as possible.

11.1.1. Comments

The first rule of shell scripting is to comment your code. You should do this right from the start, even if the script is only a couple of lines long. Shell scripts have a habit of growing from a couple of lines to many hundreds of lines as more features are added, so it's best to get into the habit of commenting your code right at the beginning.

To start with, consider having a main header or banner for your scripts. The information in the header should, at a minimum, say what the script does. Here is an example of a script header:

#!/bin/bash

#####################################################

# Name: graphconv.sh

#

# Converts graphics files from one format to another.

#

# Usage: graphconv.sh <input-file> <output-file>

#

# Author: C. Newham

# Date: 2004/12/02

#####################################################

This main header gives the name of the script, a brief summary of what it does, usage information, the name of the author, and when the script was written.

If you are using a source control system (e.g., CVS), you can dispense with the author and date as these will be stored when the script is archived. If you aren't using such a system, we strongly advise that you not only include the above information but also place in the header additional data such as modification dates and authors.

Whatever system you use, make sure that you make the format of the banner a standard across all of your scripts.

Every function should also have a header. If it is a standalone function, it should have a main header, as given above. If it is a function used locally in a script, it should have a simpler banner stating what it does, what parameters it expects, and what it returns, e.g.:

# Changes the filename extension

#

# param: $infile - the original filename

#

# returns: the modified name with new extension.

#

function change_filename( )

...

Comments should also be used frequently in your code to say what the code is doing. While we aren't about to dictate style, comments within the flow of the code are generally better on a line by themselves, while variable declaration comments are better on the same line as the variable:

startup_dir=/home/startup/  # directory with startup files

file_limit=50               # maximum number of files to process

...

if [ -d "$startup_dir" ]

then

    # the startup directory exists so read any initialisation file.

    echo "initialising file processing..."

11.1.2. Variables and Constants

Headers and comments are just one way to document your code. Another is by the use of descriptive variable names. Good variable names should give an indication of what the variable represents. Names like "x", "resn" or "procd" will only have meaning at the time that you write the script. Six months down the track and they will be a mystery.

Good names should be short but descriptive. The three examples above might have been more meaningfully written as "file_limit", "resolution", and "was_processed". Don't make the names too long; the name "horizontal_resolution_of_the_picture" just clutters a script and takes away any advantage in making the name so descriptive.

Constants should be in uppercase and should normally be declared as read-only:

declare -r CAPITAL_OF_ENGLAND="London"

You should always avoid "magic numbers" sprinkled throughout the code by using constants. For example:

if [[ $process_result == 68 ]]

...

should be replaced with:

declare -ir STAGE_3_FAILURE=68

...

if [[ $process_result == $STAGE_3_FAILURE ]]

...

Not only does this make the code more readable but it makes changing the value easier, especially if it is used numerous times in the script.

< Day Day Up >