Recently I was on a family trip to Pittsburgh. We were walking around the campus of Carnegie Mellon and I saw this memorial brick;
It got me to thinking about some of the monster databases that I have had to take over for clients. When I take over a project, often I am spending a great deal of time just trying to figure out what the developer was trying to do.
Our earlier posts on this blog are generally concerned with improving the user experience(better printing workflow) or getting more out of your data (One Report two sets of summarized data). Today I would like to return to that lowly person, the developer. Anything that I can do that can make my job easier will make be a better developer and ultimately make my customers happier. Or as my grandfather would say to my grandmother, “What would you do if I got hit by a bus?”
When I create a new script, I always try to write the outline in the comments before I add any code. By writing the comments FIRST, I am sure that they are there when I am done the script, saving me from having to go back and add it to the code.
The hardest part is knowing what to comment and what not to. I have seen developers that comment almost every line, and some who don’t use comments at all. The trick is to comment the broad strokes, I like to think of them as the ‘Turns in the Story’. You want to comment those things that you think you are most likely to forget. Also those things that are not obvious.
My rule of thumb is to try to always start with the basic pattern. Each script is written in the following pattern
- Permission. Can this script be performed at all. Check for User status, appropriate setting, appropriate record. Examples, only Super Users can perform this script. This script can only be run on a particular layout, or this script can only be done on a record with certain fields filled in.
- The body. This is the heart of the script. Make the report, make the changes etc.
- Cleanup. Be a good Boy Scout. Leave only footprints and take only pictures. Make sure you are on the right layout, the right found set, the curser is the right place. And any globals used are reset.
With this in mind, almost every script I write starts with 4 lines.
With this as a starting point I can begin to fill in either write the script from here or start putting in some comments.
Here is an example of a complete script.
Note that by just focusing in on the comments, in bold, you get the idea of what the script is doing.
Obviously not all scripts can fall neatly into this structure, but you will be surprised at the number of scripts that can. Using this as a starting point will also help you to keep your scripts understandable. Another example. Right after the Permission section, just after the ‘Done Error Trapping’ comment in my scripts. I will almost always set all the globals and variables I will need for the script. Doing this task at this point assures I will always know where to look the next time I visit the script. If I am feeling partially generous, I will even put in a comment for the exceptions. That is any variables that can’t be set at the beginning. For example a variable that can’t be defined until the user answers a dialog box.
The idea is to make sure you always know where to go to find out what a script is doing. This will make it easier for you to trouble shoot any problems months after you have forgotten why you wrote the script in that particular way. Using this framework will also help you identify things that are out of the ordinary. These are the things that will most likely need a comment.
- Jerry Salem
0 Responses to “Speak your Mind. Using Comments, part 1.”