Classic VB - Why should I comment my code? How to make my code readable?

[Merri]

When many start with programming, they don't often think about comments. This is rather natural as brains are still focusing to the main thing: understanding the code itself. However, as knowledge and skills improve, one should really start commenting his/her code. There are several advantages in this:

• Good comments help figuring out problems in the code logic and bugs as well

• It makes it easier to get back to the code as good comments help understanding the code faster

• Any other programmer can understand your code much faster

• You are likely to learn new things faster when you comment what it does...

• ... and of course you are likely to remember rarely used things faster thanks to the comments

All in all, the time you spend commenting the code is far less than what you lose when getting back to your code.


Learning the commenting

There are about as many ways to comment code as there are programmers. It takes a good while to learn the commenting and doing it as a "side process": it is first rather hard to comment and every now and then you can find lines that are particularly hard.

Without taking a good look into a lot of source, I can remember three different ways to comment codes:

• Comment procedures: what you pass in, what it returns, alternatively a general description of how it works

• Comment blocks of code: make a general description of a code block, ie. a loop; also comment some of the most important bits of the code

• Comment nearly each line: this style is the most close to writing a "story" of the code and is the most helpful for bug finding and seeing if the logic is valid

You can also use a mix of these styles. Personally, I favor the last style and I rarely comment what a procedure does: I assume it becomes selfexplanary from the procedure name and the comments I write. This shouldn't stop you from using the style you want.


Formatting the comments

Commenting procudures is a rather easy task:

' This function returns a position in a string.
' String1 = string to search from, String2 = search keyword string
' Start = start position, Compare = comparison method
Public Function CustomInStr(ByRef String1 As String, _
                             ByRef String2 As String, _
                             Optional ByVal Start As Long = 1, 
                             Optional ByVal Compare As VbCompareMethod = vbBinaryCompare) As Long
    ' ...
End Function

It could also have a few comments on how it generally works. Much of this style could be replaced with better naming convention: String1 could be SourceString and String2 KeywordString for example. I used String1 and String2 as that is what VB's native InStr has.

The next style would be to comment large blocks of code:

' This loop will process each pixel in the image
    ' Every color value is inverted using XOR
    For lngY = 0 To YSIZE - 1
        For lngX = 0 To XSIZE - 1
            lngTemp = lngXY + lngX
            larImage(lngTemp) = larImage(lngTemp) Xor &HFFFFFF
        Next lngX
        lngXY = lngXY + XSIZE
    Next lngY

The example code is a shorter one, in which the commenting still works rather well. This style tells the minimal required information to keep track of it all quickly. However, there isn't much reasoning to details.

Last, the commenting of nearly each line:

' invert the image
    For lngY = 0 To YSIZE - 1
        For lngX = 0 To XSIZE - 1
            ' use a variable to hold pixel position as it is used more than once
            lngTemp = lngXY + lngX
            ' invert the color value using XOR
            larImage(lngTemp) = larImage(lngTemp) Xor &HFFFFFF
        Next lngX
        ' speed optimization: avoid a multiplication
        lngXY = lngXY + XSIZE
    Next lngY

As you might have understood already, this style gives the most reasoning to each line. It takes a good while to comment nearly everything properly, but you can clearly find the reasons why the code is made to the form it is in.


The bad styles?

I've seen some weird styles to comment code as well. One of these was a style of commenting every single line. The bad thing was: comments were on the same line as the code! Now, each time you change the code and the length of the line varies, you also have to reposition the comment so that things look clean. I don't know why someone bothered to do it this way, but it was certainly bad for me: I had to scroll horizontally to see all of the comments (not everyone use a 1600 x 1200 resolution) and not very practical when I started to edit the code. I ended up spending four hours just moving the comments to a line before the code line (there was a lot of code like this). I didn't figure out at that time it would have been much faster to code a comment mover

Thus as a general rule: think about others as well. Even if something works for you, it might not work for others. If you are using an extension that makes it a piece of cake including the comments in the same line, someone else might not have that extension (extension is a wild guess in this case). This is important if your code will be seen by others. And staying somehow in the general style is useful for yourself as well, as it is likely the way others comment their code.


Not comments only

Some other factors improve core readibility as well:

• Giving describing names to variables, constants and procedures

• Indenting the code properly: indent the procedure content, indent loop contents, indent any generalizing statement such as With ... End With

There are several coding styles, each having their advantages and disadvantages. Generally a good thing is to somehow distinguish the datatype of a variable: blnDone, lngTemp, strCaption and so on help to know what kind of datatype is in use. This makes replacing code easier as well, as there is clearly something separating a variable from a function call, for example (so the function call's portion doesn't get replaced if it happens to be the same a the old variable name).

Personally, I haven't taken a look into documents defining coding styles. The thing has grown into me over time and it isn't a long time since I was still using variable names A, B and C very often (which I started to use with Commodore 64 about 15 years ago when I started out with programming). There is some advantage in having some kind of clear standard in your own coding style: it makes it approachable to others. Microsoft has its own page about it, which is probably the main standard you want to learn: the Visual Basic Coding Conventions. And trust me: it is better to learn them early on than to learn them over time like I did. I still have trouble with many of the conventions as I'm used to my own old habits.


Putting it all together

• Comments are helpful for you and others alike

• Having a common coding convention improves code readibility

• Indenting code makes it easier to separate different parts of code from each other

Commenting the code is the most free of formalities: you can do it as you like, even include jokes to lighten up all the hard reading someone else are doing. As long as the comments help to understand to code, they are useful. And when used effectively, comments can help. Think about others and yourself: learn to use comments, follow the general coding conventions and indent the code.