Commenting Your Code

In a recent article on Coding Horror Jeff Atwood was discussing a topic about not only putting in pertinent comments in your code, but refactoring your code so it doesn't need comments. I do not believe in commenting my code other then to put a header comment in a routine to describe what the routine is supposed to do. I researched some standards and practices that are published and they basically confirmed what I normally do, however they recommended putting in one comment about ever six lines of code. I call those "bookmarks" as I typically use them to quickly go to a section of code. I am able to do this because I code in a descriptive manner. How many times has someone created a variable called "x" or reused the same variable for different purposes? It's extremely difficult to look at variables and ask "What is that used for?" or to see a variable used a certain way in one place and then when you try and change it, you find out that it is used differently in another location of the code.

If you do not currently have a standard in place then that is really the first thing that you should do. A standard naming convention is only half the battle. For example Integers will start with int, Recordsets will start with rst and so on. But you still need to use a variable name. And this is where most developers become too lazy. It is much easier to type intLoop then it is to say intRstPrimaryCounter. Just glancing at the code I would say that intLoop is an integer used to loop through something like a For...Next loop. However, intRstPrimaryCounter tells me that it is going to be used to count through a number of records in the rstPrimary Recordset.

But you need to be consistent, you shouldn't call it rstPrimary in one spot and that rstPrimaryRS in another. As I have mentioned before I customize Pivotal CRM for a living, and the application comes with a large set of source code for the business layer which is written in VB. Over the course of time and the different developers that wrote the original code you can that they had a standard in place but they were not consistent on what they called their variables. In some places the system reference is mobjError and in others it is mrdaError. This becomes frustrating because you have a tendency to reuse code from multiple business rules and some will have mobjError references and some will have mrdaError references.

Bottom line, start a database or excel spreadsheet and record the variable names you use for common references. It will save you time and pain in the future.