On commenting and debugging your code (Kilala.nl (Cailin Coilleach)) by Cailin Coilleach
When writing shell scripts for my customers I always try to be as clear as possible, allowing them to modify my code even long after I'm gone. In order to achieve this I usually provide a rather lengthy piece of opening comments, with comments add throughout the script for each subroutine and for every switch or command that may be unclear to the untrained eye.In general I've found that it's best to have at least the following information in your opening blurb:
* Who made the program? When was it finalised? Who requested the script to be made? Where can the author be reached for questions?
* A "usage" line that shows the reader how to call the program and which parameters are at his disposal.
* A description of what the program actually does.
* Descriptions for each of the parameters and options that can be passed to the script.
* The limitations imposed upon the script. Which specific software is needed? What other requisites are there? What are the nasty little things that may pop up unexpectedly?
* What are the current bugs and faults? The so-called FIXMEs.
* A description of the input that the program takes.
* A description of the output that the program generates.
Equally important is the inclusion of debugging capabilities. Of course you can start adding "echo" lines at various, strategic points in the script when you run into problems, but it's oh-so-much nicer if they're already in there! Adding those new lines is usually a messy affair that can make your problems even worse :( I usually prepend the debugging commands with "[ $DEBUG -eq 1 ] &&", which allows me to turn the debugging on or off at the top of the script using one variable.
And finally, for the more involved scripts, it's a great idea to write a small test suite. Build a script that actually takes the real script through its loops by automatically generating input and by introducing errors.
Two examples of script where I did all of this are check_suncluster and check_log3 with the new TEC-analysis.sh on its way in a few days.
So far, TEC-analysis.sh checks in at:
* 497 lines in total.
* 306 lines of actual code.
* 136 lines of comments.
* 55 lines of debugging code.
Approximately 39% of this script exists solely for the benefit of the reader and user.
Posted in: code , comment , debug , programming , scripting