// I have a comment…

by Robert Kozak (Delphi R&D)

A couple of months ago I had the opportunity to review some code that I wrote when I first started working with Delphi. I hate to admit it but it was pretty bad. A very humbling experience for sure. My skills are vastly improved since that time. In fact, I've notice changes in just a few months. Have you ever gone back and looked at the code that you wrote six months ago? I bet that the thought going through your head was "What was I thinking? There is no way I wrote that."

If you ever had to debug your own code from a previous project I bet it was painful. It is even worse if you have to debug someone else's code. The only thing that can help the pain is good comments. Notice I said "good" comments. Bad comments are worse than no comments at all. For example look at the code snippit below. What does it do?

The comments in the above snippit are utterly worthless. It doesn't help you tell what the code does. Is this better?

The secret to writing a good comment is to ask yourself why rather than how. In your comments don't try to write how the code works (that code itself is the how) but explain why you wrote it. Typically, when commenting is done right there is less of it.

(* Categories of comments *)

There are basically 5 categories of kinds of comments. I'll explain them from the worse to the best:

Repeat the code

This type of comment restates the code in different words without adding any additional information. This type of comment is to avoided like the plague.

Explanation of the code

This type of comment is used to explain complicated or tricky code. Although these types of comments can help it much better to rewrite the code so that it is easier to understand.

Markers

Markers are used as a temporary note to yourself or other programmers on your team. With Delphi 5 you now have //TODO comments recognized by the IDE. A friend of mine uses //\\ to mark code he wants to come back to later while I tend to use my initials //rk: When the project is completed these markers should be removed.

Summary of the code

This type of comment summarizes the code in a few sentences. This is better than just repeating the code because it allows someone not familiar with your code to scan through quickly.

Description of the code's intent

This explains the purpose of the code, or in other words, the why. Comments of this type are easy to read and give you the information required to understand the code it refers to.

{Commenting Techniques}

Okay, now that we know we want to use summary and intent commenting types lets take a look at some techniques to use them properly. There are basically 5 areas you want to use comments: individual lines, code paragraphs, data structures, routines, units and projects.

Individual lines

If you are writing good code (that is the point, right?) then you will only comment individual lines in two cases. In the first case, the individual line is complicated enough that it needs an explanation. Although, it is easy to rewrite a complicated routine to clarify its intent it is hard to rewrite an individual line. In the second case, the individual line had an error and you want to record it.

I used to use endline comments a lot. These are comments that are added to the end of the line, as in:

The endline comment usually doesn't have enough room to clarify the intent and so degenerates into restating the how. Endline comments also are hard to keep aligned and tend to use abbreviations. The only time that endline comments would be appropriate would be to annotate data declarations, maintenance notes, or to mark the end of a block (//end if, //end while, etc. ). Data declarations tend to be short so there is more room for an endline comment. If you did place the comment above each data declaration it would be harder to follow the data structure itself. Maintenance notes tend to be short and feature initials, date and bug numbers and since they don't actually comment the intent of the code an endline comment is appropriate.

Code paragraphs

This is the most common way (and best) to comment your code. Commenting this way should describe the intent of the code following the comment. Don't forget, that you should concentrate of the why and not the how. These types of comments should prepare the reader for what is to follow. They should be able to scan the comments and get a good idea what the code does.

Data declarations

Comments that describe variable declarations describe aspects of the variable that the name itself can not, such as its units (as kilometres, feet, pounds, dollars etc.). Variables should be commented where they are declared and if you have any flag variables where each bit has its own meaning then each of these should be commented.

Routines

Some people while tell you that each routine needs this huge monolithic comment header. This is ridiculous. For one, this makes for comments that a laborious to read and far away from the code it describes. Good comments should be at close proximity to the code it describes, usually a few lines of comments are sufficient. There are times though a particular routine does need a little more info. Take for example the following snippit:

I always had trouble with this because I kept forgetting which was the Sender and which was the Target. Even in my own code, for routines with a Source and Target, I kept forgetting which was the incoming and which was the outgoing variable. A comment can go a long way in helping alleviate this confusion. Some other things you may want to put in a routine comment (as needed) are: interface assumptions, change history, routine limitations, global effects, algorithm's source, and design patterns used.

Units and projects

Finally we come to units and projects. When commenting units and projects you want to give a short description of the project or unit and describe the purpose of each file. You may also want a change history, description of major objects and design patterns used. You should also include you name and how to reach you either by phone number or email so that anyone maintaining your code can get a hold of you so you can explain the silliness you wrote. And if appropriate a copyright notice.

//end file

If you are like me you need to work on your commenting skills. Commenting doesn't have to be hard or time consuming. Just remember that your code is the how and your comments are the why. If you keep this in mind I have no doubt that even I could make sense of your code.

{ TODO: For additional reading see Code Complete by Steve McConnell, Microsoft Press }

Biography

Robert Kozak is a member of the Kylix R&D team and has been with Borland since the later half of 1999. Robert has been involved as a user of Delphi since the initial beta and since he joined Borland he has been involved in the development of Borland C++ Builder 5 and now Kylix (Top Secret project to bring Delphi and BCB to the Linux platform.) Robert was involved with the start of TaDDA! (Toronto Area Delphi Developers Association) which later merged with TDUG (Toronto Delphi Users Group). Robert continues to stay active in the user community and is active on the Borland newsgroups.