Commenting Scripts
When you look at a script someone else created—or you created a long time ago—it isn’t always obvious what it’s trying to do. To help keep things clear, add comments to your script. You add each comment using a Comment script step. This step has just one option: the text of the comment itself. The comment step is special for two reasons. First, it doesn’t do anything. Second, it shows in bold when you view your script in the Edit Script window. You can see a commented script in Figure 15-1.
Use comments to document anything important about the script. Here are some things you may want to include in a comment or set of comments:
What the script does
Who wrote the script
The date the script was written
The date, if any, the script was last edited
Who edited the script
Anything special about how or when the script should be run, like whether only some database users can run it, or if the script requires parameters to do its work (see Script Parameters).
Documenting scripts is standard operating procedure among programmers, for a couple reasons. First, if something’s wrong with the script, or it needs to be changed, you’ve got extra information that could help. You know exactly what the script should do, plus you have a list of people who’ve worked on it and can give you background or pointers. Second, the date can help identify whether a particular business rule was in effect that made certain parts of a script necessary. If you see that script is really old, you may decide ...