It is surprising how quickly we forget how to use scripts we had written, let alone, what they were for. So it is even more difficult for others to know how and whether to use your script. You can avoid wasting the efforts you put into the problems you solved with your script by simply adding some friendly “help” output.

Here is some basic information you should include:

• Summary description
• Form of use—basic syntactic usage
• Description of usage syntax; i.e., input parameters
• More detailed information, if necessary.

Ideally, this information is shown whenever the user types invalid input (such as not entering a parameter when there should be at least one). Alternatively, the information should be included as comments, at the top, so a user can read the source (without having to understand the source). As the following shows, however, having run-time output can be even easier than creating a comment block:

[bash]
#!/bin/bash
## TODO: Add functionality to this script
## TODO: Add support for -h and –help arguments (see future post)
## 2013-07-22 Created by Bill Lee <email address>

if [ -z "$1" ]; then
more <<ENDHERE
Here, you should add a brief description about how your scripts work and why it exists.

Form:
`basepath $0` {parameters}

where:
parameters include a description for any parameters…

And, add any other useful information…
ENDHERE
exit 24
fi
.
.
.
[/bash]

It is a good idea to have a comment block at the top of your code. As lines 2 and 3 show, reminders to yourself (and others) about what you plan to do to enhance the script, keep your thoughts from getting lost to the ether. It is also good to have a log of changes, especially when others are using your script, so that users know what’s changed—if they care.

What makes it easy to write the help content starts at line 7 using bash’s “heredoc” feature. Heredoc allows you to create literal content, in place, that can be redirected to a command. By redirecting to more, you get free screen handling.

It is always nice to show the script’s invocation syntax; i.e., the arguments that can be entered. Common syntax usage:

• literal information is simply shown
• Items surrounded by {} are required but are filled in with an invocation specific value.
• Items in [] are optional
• … means “more of the same”
• You may use * to mean zero or more of and + to mean 1 or more of; useful shorthand, but not everyone will know this syntax.

Line 11 uses a little trick so that you needn’t explicitly specify the name of the script. Then, should you rename the script, you needn’t worry about forgetting to update the “help” info.

Line 17 is the end of input. At line 18, return a non-zero value so that other scripts can test whether the script was successful (not!).

When users are having problems, like when they enter the wrong number of parameters, that is a good time to show them how to use your script (that’s the simple example in line 6, above). Maybe a script does not require parameters; or “invalid input” is more complex that the simple check shown above. You can then create a function that outputs this content; then you can call it from anywhere in the script. You should put such a function near the top of the script so that readers of the source code will see it right away.

[bash]
#!/bin/bash
## TODO: Add support for -h and –help arguments (see future post)
## 2013-07-22 Created by Bill Lee <email address>
function show_help() {
more <<ENDHERE
Here, you should add a brief description about how your scripts work and why it exists.

Form:
`basepath $0` {parameters}

where:
parameters include a description for any parameters…

And, add any other useful information…
ENDHERE
}

if [ -z "$1" ]; then
show_help
exit 24
fi
[/bash]

Just think about what you’d want to know if you found a script written by someone else. By clearly and simply describing what your script does, your work does not go to waste and reduces the chances that someone doesn’t just say “it is easier for me to write my own script” and waste both your efforts.