Argee's Access Blog

At the end of August, a discussion at my home away from home, UtterAccess.com piqued my interest in the topic of how experienced Access developers viewed the importance of commenting their VBA Code. I decided to conduct a brief survey of two groups, Microsoft MVPs, and UtterAccess VIPs. I specifically notified Access and Excel MVPs as well as the VIP group at UtterAccess.

While there weren’t quite as many opinions as their were people completing the survey, there certainly is a broad range of opinions.

Dennis, an UtterAccess member who was unable to complete the survey because he was away while it was open for response posted a forum message that pretty well sums up my own position on the question. He said in part,

“Commenting code was described by one of my college instructors as one of the most important, but least prioritized steps of the programming process. And I believe he was (and is) 100% correct.
One should never assume that the purpose of a block of code is self-evident. Even if you've used the same module over and over, that module should be documented so that someone (even you) in the future will quickly be able to see HOW and WHY a block of code is doing what it does.
Commenting costs nothing to compiled code, and is worth it's weight in gold to people charged with improving and re-using code. After all, the cliché says "time is money" and the amount of time saved with a few lines of text within a block of code can be enormous.
There, that's about it, in a nutshell.”

I should mention that I did not submit a response to the survey myself; I wanted to leave the answers to others and let the results fall where they may. The results were not particularly startling. They do reflect a broad range of opinion among the respondents. More than half of the 57 people answering the survey rated commenting as being either very important or absolutely essential.

The numerical results, however, only tell part of the story. The survey included two open-ended questions, ‘Briefly describe how you use commenting in your own work and the depth of detail you include in your comments.’ and ‘What would you describe as the single most important reason for including comments in programming code?’

A common theme for the first set of open-ended responses was, “to help me remember what I did and why.” Some of these comments expanded the theme to include “others who might have to follow-up on my work.”

In response to the second open-ended question, one person put it this way, “1stly To remind me of what I wrote and how the code works...I sometimes don't view project for long periods of time. 2ndly so that if or when I expire someone else can take up where I left off.”

There were a few problems with the survey, some caused by my oversight when I designed it and some caused by the the survey software itself. Two people reported either being unable to submit their responses on the the survey site or being unable to edit/include comments that were greater than 255 character. I won’t complain too loudly about the survey site, however, since I used the free survey tool that is available if you register on the site.

As to survey design issues, I neglected to include a ‘none’ category in the question about programming languages other than VBA. That cause the ‘other’ response to be somewhat ambiguous.

All in all, however, I’d have to say that devising and implementing the survey and analyzing the results has been an interesting exercise. I have a few other ideas that I may try in the future. The full survey report is available in pdf format here.

I would like to publicly thank the UtterAccess VIPs and my fellow MVPs who took the time to respond to the survey.