bash Cookbook

Documenting Your Script

Problem

Before we say one more word about shell scripts or variables, we have to say something about documenting your scripts. After all, you need to be able to understand your script even when several months have passed since you wrote it.

Solution

Document your script with comments. The # character denotes the beginning of a comment. All the characters after it on that line are ignored by the shell.

#
# This is a comment.
#
# Use comments frequently.
# Comments are your friends.

Discussion

Some people have described shell syntax, regular expressions, and other parts of shell scripting as write only syntax, implying that it is nearly impossible to understand the intricacies of many shell scripts.

One of your best defenses against letting your shell scripts fall into this trap is the liberal use of comments (another is the use of meaningful variable names). It helps to put a comment before strange syntax or terse expressions.

# replace the semi with a blank
NEWPATH=${PATH/;/ }
#
# switch the text on either side of a semi
sed -e 's/^\(.*\);\(.*\)$/\2;\1/' < $FILE

Comments can even be typed in at the command prompt with an interactive shell. This can be turned off, but it is on by default. There may be a few occasions when it is useful to make interactive comments.

See Also

• “shopt Options” in Appendix A gives the option for turning interactive comments on or off