• Home
 · 
• Coding Standards
 · 
• Comments the Good, the Bad, and the Ugly

Comments the Good, the Bad, and the Ugly

This article discusses commenting: why we use it, how to do so properly, and how to avoid poor practices and pitfalls.

Rate Comments the Good, the Bad, and the Ugly

• 1
• 2
• 3
• 4
• 5

(8(8 Vote))

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.


Conclusion

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.


Bibliography

Code Complete, Microsoft