Documenting Shell Script

Several times I have said that others may be using your scripts, and that you might be using your own script long after you can remember how you wrote it or why. For both reasons, it is important to document your work. This documentation can take several forms, as described in the following sections.

The comment lines within a script describe what the script is doing and why. A large block of comments at the beginning of the script should also be included. This block should:

1. List the author, date of creation, and copyright, if applicable
2. Define the purpose of the script in general terms
3. Explain any dependencies (other programs that the script uses)
4. Define the syntax expected on the command line when the script is launched

Most scripts require parameters of some sort, such as a filename or URL. When a script is started without any parameters, it should print a usage message to the screen. This message describes the script’s purpose (in one or two lines), and how the script should be launched, such as the command line options or types of files that are expected. This information is similar to the comments within the script, but is available for those who don’t know enough about shell scripting to look at the script itself.

For complex scripts that perform important functions within an organization, consider writing “real” documentation, separate from the script itself. This may be an HTML file or other online help, or a few pages in a word processor. The purpose of the documentation is to help new users of the script know how to use it correctly, and to help the organization track what resources are at its disposal.

Click on the Exercise link to test yourself on the material in this module.
Documenting Shell Script - Exercise