Comments - the Good, the Bad, and the Ugly

Submitted on: 1/28/2015 10:55:00 PM
By: Peter M. Dodge (from psc cd)  
Level: Beginner
User Rating: By 7 Users
Compatibility: VB 3.0, VB 4.0 (16-bit), VB 4.0 (32-bit), VB 5.0, VB 6.0, VB Script, VBA MS Access, VBA MS Excel
Views: 360
     This article discusses commenting: why we use it, how to do so properly, and how to avoid poor practices and pitfalls.


Commenting: the Good, the Bad, and the Ugly
A guide to proper commenting practices by Peter Dodge

What is a comment?
A comment in Visual Basic is any statement that starts with either an apostrophe (') or the keyword "REM" (short for remark). Used properly, comments a a powerful tool to clarify your program.

Why do we use commenting?
Programmers use comments to document their code, to explain why a code is doing certain actions, and to document the uses of various variables.

What are good, common commenting practices?
There are many good commenting practices in the programming industry. Some of the more common ones are outlined below:

Variable Documentation
A very frequently encountered use of commenting is to document variables and how they are used.
For example:

' The length of the longest side.
Dim a as Integer
' The lengths of the other sides.
Dim b as Integer
Dim c as Integer

As some people reading this article have noted, these variable names are not very descriptive. The use of descriptive variable names is beyond the scope of this article.

Block Header Comments
A good but often overdone commenting process is making headers for you forms and modules, explaining the purpose of the file. Revision history can also be added here.

Procedure Header Comments
A not so often used but very good commenting practices is to have a large haeder at the beginning of a procedure or function explaining the purpose of the fucntion or sub. Function headers should also include the nature of the data returned.

When comments get bad
Comments, however can be used in bad ways as well, like many other programming practices. The main incorrect use of comments is when the comment merely explains what the code does. This is nothing that the programmer looking at the code could not deduce. The proper use of comments is to not only explain what the line(s) of code is doing but why the code is doing this. This makes the line(s) of code in question much easier to understand, and makes the original intention of the code clear.

Another point of content with comments is if they are left unmaintained after they are written. When this happens, the comment can be misleading. This can cause serious problems, especially in maintainance programming.

Comments, like most things, is neither inherently good or bad. It is the way in which they are used which makes them good or bad. This article attempts to show the things to try and the things to avoid.

Code Complete, Microsoft

Other 1 submission(s) by this author


Report Bad Submission
Use this form to tell us if this entry should be deleted (i.e contains no code, is a virus, etc.).
This submission should be removed because:

Your Vote

What do you think of this article (in the Beginner category)?
(The article with your highest vote will win this month's coding contest!)
Excellent  Good  Average  Below Average  Poor (See voting log ...)

Other User Comments

 There are no comments on this submission.

Add Your Feedback
Your feedback will be posted below and an email sent to the author. Please remember that the author was kind enough to share this with you, so any criticisms must be stated politely, or they will be deleted. (For feedback not related to this particular article, please click here instead.)

To post feedback, first please login.