Word Document Properties

Chapter 3: Writing Structured VBA Programs
08_046500 ch03.qxp 12/5/06 5:34 PM Page 77

---

Writing basic comments
Comments can take a number of forms. The pseudo-code comment is the first
kind of comment that everyone writes because it’s the kind of comment that’s
most natural to use. Developers quickly move on to adding documentation
comments, such as who wrote the program or when it was originally written
and a list of updates made to code. Some developers move on to better com-
ments at this point.
One of the more important comments that you can add to your code is why
you chose to write the program in a certain way. Simply saying that the code
performs a specific task isn’t enough because you can usually perform the
same task in several different ways. Telling why you made certain choices
can reduce mistakes during code updates and serve as reasons for perform-
ing updates later, when your coding technique improves.
As a good programmer, you should also include mistakes that you make in
the code as comments if you think that someone else might make the same
mistake. These experiential comments have helped me in many situations
because I actually end up using them for notes. When I start a new project,
I look back at my notes for things that I should avoid.
Knowing when to use comments
Use comments wherever and whenever you think that you need them. You
might think that comments are difficult to type and include only one or two
paltry comments for each program that you write. You’re correct — writing
good comments can be time consuming and can be difficult because writing
them makes you think yet again about the code. However, the programs with
the fewest comments usually generate the most head scratching during an
update. In fact, I’ve seen a few situations where the lack of comments in code
actually caused a company to start writing the code from scratch during an
update rather than pay someone to spend the time relearning what the old
code meant.
Understanding how to create 
a good comment
A 
good
comment is one that you can understand. Don’t use fancy terms —
write everything in plain terms that you can understand. When you feel that
you need to explain something, feel free to do it. Good comments should
answer the six essential questions: who, what, where, when, why, and how.
Make sure that your comments are complete and that they fully answer any
questions that someone reading your code might have.
78