Friday, April 28, 2000

Programming Tips & Tricks #0001---Working with someone else’s code

Tips & Tricks

Working with someone else’s code

The scenario (all too familiar):
You have a new job, and your first programming assignment is to modify a Visual Basic program that was written by another programmer who has left the company. The program is hard to follow. It has no comments, all of the variables are haphazardly named, and all the forms and controls were left with their default names, such as Form1, Form2, Command1, Option1, etc. You’re overwhelmed.

This is not an unusual feeling. In fact, you can feel the same way about your own code a year or so after writing it. So I emphasize these precautionary measures to ensure easy comprehension by others:

1. Option Explicit is coded in all of your modules (this ensures that Visual Basic enforces that all variables are declared before using them)
2. All variables and controls are named using a formal naming convention (i.e. Hungarian Notation)---this makes modifying the program somewhere down the road much easier
3. Code that is repetitive in nature is consolidated into procedures and called from within the program
4. Every module has comments describing its major functions and features
5. Code that is anything out of the ordinary is also commented

Sounds great, but how do these ‘rules’ help you modify someone else’s code? Unfortunately, I’m suggesting you correct the mistakes of the past.

Of course, before you do this, you need to get your supervisor or project leader to ‘buy into’ that plan. Obviously, if he or she is expecting the program modification to be made in about an hour, so taking a week to clean the code and make the modification won’t make you a hit in the Employee cafeteria.

However, I can almost assure you this won’t be the last time this program is modified. Biting the bullet now and cleaning it up will make things much easier on the next junior programmer who finds himself in the uncomfortable position of modifying this code.

Once you have the go-ahead to proceed, the first thing to do is to ensure that Option Explicit is coded in the General Declarations Section of every module in the program. -- if it’s not, add it manually -- and then run the program. Guess what? The program no longer runs. Why?

Coding Option Explicit will cause VB to mark, as a syntax error, every instance of a variable that hasn’t been declared---potentially lethal errors in a program. At this point, you need to identify the variables that haven’t been declared, and explicitly declare them, with a defined type (i.e. Integer, String, Date). While you’re at it, this wouldn’t be a bad time to rename variables using either Hungarian Naming Convention, or a naming convention in use at your company. Using Visual Basic’s Search and Replace features can make this task a lot easier than it sounds.

With all of the variables properly declared and named properly, now is a good time to name those forms and controls in a meaningful way. Keep in mind that when you change the name of a control, the code associated with it can appear to be ‘lost,’ finding its way into the General Declarations Section. To avoid this, first rename any event procedures associated with the control manually with the new name of the control—then bring up the Properties Window for the control and change its Name property there.

At this point, make sure the program runs okay. You’ll find you now have an understanding of how the program works -- so much so, that you should be able to identify code that can be centralized in a subprocedure or function. Along the way, insert comments in your code explaining what’s going on. Write those custom procedures and place them in either a Form Module or a Standard Module (every Visual Basic program I write has one).

Now, with the Visual Basic program nicely sanitized, it’s time to code that simple modification you’ve been asked to make. Hopefully it will be a piece of cake.