In the pet examples above an array of cPet objects is used to hold the pets. This works well if you know exactly how many pets you have. But what happens if you adopt another stray puppy or your cat has kittens?
One solution is to use a Collection object instead of an array. A collection object looks a little like an array but lets you add and remove items without worrying about the declared size, it just expands and contracts automatically.
25 Effective Programming
When programming effectively in any computer language, whether it is VB or C++ for example, there should be consistency to your style, it should be organized, and should aim to be as efficient as possible in terms of speed of execution and use of resources (such as memory or network traffic). With established programming techniques, errors can be reduced to a minimum and be more easily recognized, and it will make the job of the programmer much easier and more enjoyable.
There are many different aspects to writing reliable programs. For a short program used interactively and only by the author it can be reasonable to break all the rules in the service of quickly getting the answer. However, if that little programs grows into a large program you will end up wishing that you had started on the right path. Each programming language has its strengths and weaknesses and a technique that assists in writing good programs in one might be unnecessary, impossible or counterproductive in another; what is presented here applies to VB6 in particular but much of it is standard stuff that applies or is enforced in Pascal, C, Java and other similar imperative languages.
25.1 General Guidelines
These suggestions will be described in greater detail further below. None of these can be called rules and some are controversial, you have to make up your own mind based on the costs and benefits
• Write comments that explain why you do what you do. If the code or the problem being solved is especially complex you should also explain why you chose the method you did instead of some other more obvious method.
• Indent your code. This can make reading the code for others easier and makes it easy to spot where statements have not been closed off properly. This is especially important in multiply nested statements.
• Declare all variables, enforce this by placing Option Explicit at the top of every code module,
• Use meaningful variable and sub routine names. The variable FileHandle means a lot more to us humans than X. Also avoid the tendency of abbreviating names as this can also make it hard to read code. Don't use FilHan where FileHandle would be clearer, • In the argument list of functions and subs declare all arguments as ByRef. This forces
the compiler to check the datatypes of the variables you pass in,
• Declare variables, subs, and functions in the smallest possible scope: prefer Private over Friend and Friend over Public.
Effective Programming
• Have as few variables as possible declared Public in .bas modules; such variables are public to the whole component or program.
• Group related functions and subs together in a module, create a new module for unrelated routines,
• If a group of variables and procedures are closely related consider creating a class to
encapsulate them together,
• Include assertions in the code to ensure that routines are given correct data and return correct data,
• Write and execute tests,
• Make the program work first and work fast afterwards
• Where a variable can hold a limited range of discrete values that are known at compile time use an 'enumerated type,
• Break large programs into separate components (DLLs or class libraries) so that you can reduce the visibility of data and routines, to just those other pieces of code that need to use them,
• Use a simple prefix notation to show the type of variables and the scope of routines.
25.2 Declaring variables
Earlier in this book, you may have been taught to declare variables with a simple Dim statement, or not at all. Declaring variables on different levels is a crucial skill. Think of your program as three branches: The module (open to all forms), individual forms, and the sub programs themselves. If you declare a variable in your module, the variable will retain its value through all forms. A dim statement will work, but it is tradition to use "Public" in its place. For example:
Public X as Integer
Declaring something at the top of your form code will make it private to that form, there- fore, if you have X=10 in one form, and X=20 in another, they will not interfere. If the variable was declared public, then there would be interactions between the values. To declare something in your form, it is traditional to use "Private".
Private X as Integer
And finally, there are the subprograms. Dimensioning variables only to a subprogram is highly effective, this way you can use default variables (such as sum for sums) in all subs without the need to worry about one value changing because of another section of code. There is, however, a twist. Dim, what you are accustomed to, will not retain the value of the variable after the sub is done. So after rerunning the sub, all the local variables in the sub will be reset. To get around this, a "Static" may be used.
Comments
Some of you may want to take the easy way out, and just use Public on everything. How- ever, it is best to declare something on the smallest level possible. Generally arguments are the best way to send variables from one sub to the other. This is because arguments make it far easier to track exactly where variables are being changed in case of a logic error, and almost limits the amount of damage a bad section of code can do. Declaring variables is, again, useful when using default variables. Common default variables are:
I for loops J for loops
Sum(self explanatory) X for anything
So, rather then making variables I and II or Sum1,Sum2, you can see why keeping variables local is a useful skill.
25.3 Comments
Every programmer I know dislikes writing comments. I don't mean just illiterate script- kiddies writing some brain dead Visual Basic Script to delete all the files from some poor grandmother's PC, I mean them and everyone up to people with multiple Ph.D.s and honorary doctorates.
So if you find it difficult to convince yourself that comments are a good idea you are in good company.
Unfortunately this isn't a case of you and I being as good as them but of them being as bad as us. Good comments can be critical to the longevity of a program; if a maintenance programmer can't understand how your code was supposed to work he might have to rewrite it. If he does that he will also have to write more comments and more tests. He will almost certainly introduce more bugs and it will be your fault because you didn't have the courtesy to explain why your program was written the way it was. Maintenance programmers are often not part of the original team so they don't have any shared background to help them understand, they just have a bug report, the code and a deadline. If you don't write the comments you can be sure that no one will add them later.
Comments need to be written with the same care and attention as the code itself. Sloppily written comments that simply repeat what the code says are a waste of time, better to say nothing at all. The same goes for comments that contradict the code; what is the reader meant to believe, the code or the comment. If the comment contradicts the code someone might 'fix' the code only to find that it was actually the comment that was broken.
Here are some example comments:
Dim cbMenuCommandBar As Office.CommandBarButton 'command bar object
That comes from one of my own programs that I created by hacking at a template provided by someone else. Why he added the comment is beyond me, it adds nothing to the code which contains the word CommandBar twice anyway!
Effective Programming
Public WithEvents MenuHandler As CommandBarEvents 'command bar event handler
Same degree of pointlessness. Both examples are from programs that I use everyday. Another from the same program which shows both a good comment and a pointless one:
Public Sub Remove(vntIndexKey As Variant)
'used when removing an element from the collection
'vntIndexKey contains either the Index or Key, which is why 'it is declared as a Variant
'Syntax: x.Remove(xyz)
mCol.Remove vntIndexKey End Sub
The first comment line simply repeats the information contained in the name, the last comment line tells us only what we can easily glean from the declaration. The middle two lines say something useful, they explain the otherwise puzzling use of the Variant data type. My recommendation is to delete the first and last comment lines, not because they are incorrect but because they are pointless and make it harder to see the comment that actually matters.
To summarize: good comments explain why not what. They tell the reader what the code cannot.
You can see what is happening by reading the code but it is very often hard or impossible to see why the code is written as it is.
Comments that paraphrase the code do have a place. If the algorithm is complex or sophis- ticated you might need to precis it in plain human language. For example the routines that implement an equation solver need to be accompanied by a description of the mathematical method employed, perhaps with references to textbooks. Each individual line of code might be perfectly clear but the overall plan might still be obscure; a precis in simple human language can make it plain.
If you make use of a feature of VB that you know is little used you might need to point out why it works to prevent well-meaning maintenance programmers cleaning it up.
If your code is solving a complex problem or is heavily optimized for speed it will need more and better comments than otherwise but even simple code needs comments that explain why it exists and outlines what it does. Very often it is better to put a narrative at the head of a file instead of comments on individual code lines. The reader can then read the summary instead of the code.
25.3.1 Summary
• Comments should add clarity and meaning,
• Keep the comments short unless the complexity of the code warrants a narrative descrip- tion,
• Add comments to the head of each file to explain why it exists and how to use it, • Comment each function, subroutine and property to explain any oddities such as the use
Avoid Defensive Programming, Fail Fast Instead
• If a function has side effects explain what they are,
• If the routine is only applicable to a certain range of inputs then say so and indicate what happens if the caller supplies something unexpected.
25.3.2 Exercises
• Take a piece of code written by someone else and try to understand how it works without reading the comments.
• Try to find some code that doesn't need any comments. Explain why it doesn't need them. Does such a thing exist?
• Search the web, your own code or a colleague's code to find examples of good comments. • Put yourself in the position of a maintenance programmer called in to fix a bug in a difficult piece of your own code. Add comments or rewrite the existing comments to make the job easier.