Why Include Comments?

Although some programmers see no value in adding comments to their code, the professional Visual Basic programmer employs a higher standard in his or her programs. Some of the practical reasons for incorporating comment documentation in your code include the following.

Description of Purpose

You always add a subroutine or function to a program with a purpose in mind. Remarks allow you to express that purpose to anyone who wishes to read your thoughts. Comments give you a chance to justify the code you wrote, even if the justification is directed only at your own sense of discipline.

Readability

Comments enhance the readability of your code by providing an alternate method, apart from the code itself, to express the logic of a code section. It is true that some code is immediately clear without remarks of any kind. Yet applications written to fill the business needs of your customers will probably involve complex calculations and user interactions. Bringing clarity to these sections through descriptive comments will make the initial programming, and maintenance programming later on, more satisfying.

Second Memory

When you have complete responsibility over a project's design and implementation, it is easy to say, "I know everything about this program. I wrote it." While that may be a true statement today, just wait until a year from now when the users spring on you the list of modifications they have been saving up until funding was available. I guarantee that you will have forgotten some parts of the application, especially if you worked on other projects in the meantime.

Unlike your memory, comments written at the same time as the code do not forget. Even when a section of code is somewhat familiar, well-written comments can save you the trouble of reading every line of code to understand the logic. If you have to find a bug in unfamiliar code, comments can help you narrow down the problem quickly. And even better than your memory, they remain with the code when you have moved on to other projects. This makes the life of maintenance programmers (and everyone is a maintenance programmer at some time) easier.

Logic Clarity

I always recommend writing your comments at the same time as you write the logic of the code. This way, you can clarify your thoughts about the flow of a routine or section. Remarks require you to write all of your code twice, once in Visual Basic, and once in your native tongue. They are much like the redundant safety systems installed on airplanes. If the main system fails, it is comforting to know that the backup system is there.

Identification

Comments let you identify important pieces of information that may otherwise be buried in documentation, or even undocumented. Most programmers naturally put their name in their code (at least code of which they are proud). Other items that can be identified in the code include the user or manager who requested a modification to the original specification, the source from which an algorithm or data was obtained, and the features of a special input or output device with which the application was designed to work.

Code Reviews

Some companies require that all applications pass through a code review, a formal critique of the program by other knowledgeable programmers, to confirm the correctness of the application logic. I have been involved in a few such reviews, and it is almost always the case that the person conducting the review has no involvement with the application under review. In a few cases, I was in meetings where non-Visual Basic programmers reviewed Visual Basic code. Although this is not an ideal situation, this makes the presence of in-code documentation vital. Although many procedural and event-driven languages share a similar syntax, the code alone is not always immediately understandable to other programmers. Comments make the translation simple.

Future Modifications

Comments make future application modifications easier by introducing the next programmer to the thought process behind sections of code. If you have thought out future enhancements in advance, you can include remarks in your code that direct other programmers to the locations within the code where modifications should be focused.

It is also important to alert programmers, whether yourself or others, to relationships in sections of your code that are not adjacent. For example, I like to include support for status bar help when the user is browsing the menu items of the main application window, such as the "Exits the application" message in Figure 3-1.

Apart from the Windows subclassing code necessary to make this feature work, I maintain a list of constants for each menu item for which a message will appear. The subclassing callback function that checks for interactive menu selection calls a function named GetMenuMessageString() that returns a string message based on the highlighted menu item's constant. If I ever need to add a new menu item (and constant), I also need to update the function that returns the strings. Therefore, I add a comment with my menu constants that reminds me to make this update.

' ----- When adding new menu items, be sure to update the
'       GetMenuMessageString() routine as well.
Public Const MNU_FILE_NEW = 1
Public Const MNU_FILE_OPEN = 2
    ...