Programmer Musings

Code Comment Guidelines

In my last post (Thoughts on Code Comments), I described two opposing camps that argue about code comments. Like much of the craft of programming, the commenting of code is too complicated for a simple set of rules.

In this post, I will describe a set of guidelines that I've adopted over the years. These guidelines have been helpful both personally and have helped direct many more junior programmers.

1. Don't Comment Implementation

Comments that describe what the code does are Implementation Comments. In theory, they allow anyone to read the comments and understand what the code is doing.

In practice, the person reading and maintaining the code should be able to read the code itself to tell what it is actually doing. So the comment is redundant and does that person no good. Anyone who cannot read the actual code to see what it is doing probably won't have the context needed to understand or change the code. Comments at implementation level probably won't teach them enough to actually change or understand the code. So, from the beginning, implementation comments are either redundant or not useful.

At some point, the code will be fixed to remove a problem and the comment will not be changed. (You can argue that the maintenance programmer should have updated the comment. I've never had the opportunity to code in the ideal world where that always happens.) Implementation level comments seem to be the most likely to diverge when the code changes.

Summary: At best, implementation comments are redundant; at worst, they are wrong or misleading.

2. Do Comment for Intent

While I can understand what a piece of code does by reading the code, I may not know what the programmer meant to do from reading the code. Commenting the intent (at a fairly high level) can go a long way to making the maintenance programmer's life easier.

For the programmer who can understand the code, an intent comment provides context. That makes evaluating and/or changing the actual code much easier. If someone is reading the comment that cannot understand the code, the intent may at least give them an idea whether they are looking at the right code.

Intent comments are usually not invalidated by code changes intended to fix bugs, since a bug normally means that the actual code did not match the intent. Intent comments can also supply context that the reader of the code needs to understand it.

Intent comments are almost always a block of text that explains a logic chunk of code that follows: a function, method, class, or tricky piece of data manipulation. It is possible for a single line comment to give intent, but that may be a sign that the code you are commenting deserves to be a subroutine with an intent-revealing name.

Summary: Intent comments are a message to the reader of the code to give context needed to understand the implementation.

3. Do Comment Tricky Algorithms

Under some circumstances, solving a problem requires a tricky or unusual algorithm. (Not as often as less experienced programmers think, but it does happen.) This algorithm should be commented. This will be a cross between an intent comment and an implementation comment. You would probably give more implementation details (focusing on why this particular implementation is necessary) than would normally be appropriate when describing intent.

This simplest version of this comment names a known algorithm and references a source for more information. If you need to re-implement a standard algorithm, this would be the best approach. You might even provide information on why you chose this algorithm instead of another.

This kind of comment is a life-saver for the maintenance programmer. It helps avoid the circumstance where you fix an unusual piece of code only to subtly break some of its intended effect. This kind of comment also makes it possible to replace the algorithm with something more standard, if something is discovered or created at a later time. We've all seen code that has some weird effect that we compensate for all over the code, but no one is willing to change because we don't know why it does what it does.

Summary: A tricky algorithm should be commented for how it works and why it must be done this way. This reduces chances of accidentally changing behavior and maximizes the chances of replacing special code as understanding improves.

4. Do Comment to Justify Optimizations

A variation of the Tricky Algorithm comment involves the favorite vice of many programmers: optimization. In the past, I've lumped Optimized Code in with Tricky Algorithms without making a distinction.

In recent years, I've had to modify my thinking after working with a programmer who is quite adept at optimizing. In some code reviews, I pointed out the cost of maintaining some optimizations and asked for justification of the changes. This normally resulted in some code profiling. Sometimes, the optimization was reverted after actual measurement showed little benefit. Other times, we got a wonderful comment explaining the reason for the optimization along with numbers proving the benefits.

As a result, I've come to suggest that any tricky code written for the sake of optimization should have actual performance numbers added that explain the benefits of the optimization. We know from plenty of sources that programmers are not very good at identifying actual bottlenecks that require optimization. This requirement forces the programmer to actually profile the code to document the benefit. The team can now reasonably evaluate whether or not the optimization is worthwhile. We might be willing to deal with some hairy code to give a 5X speed increase in code that is called a lot. On the other hand, a 5% speed increase in code that is not called often is probably not worth the cost.

Summary: You should profile before optimizing. So add the results of the profiling to the comment on the tricky algorithm you are using to optimize.

5. Do Comment Public APIs

Over the last 15 years or so, one really strong push in programmer documentation is API documentation. This is normally automatically extracted from the code and reformatted into a nice web-based interface. The first version of this approach that most people are aware of is probably the Javadoc system introduced with Java. The idea was to generate more benefit for standardizing the class and method comments by automating a way of extracting the comments from the code and generate a nice API document.

Documenting the public API of a module or class is a great benefit to anyone using that module or class. API documentation should be written as more of an intent comment with the addition of inputs, outputs, and pre-conditions. This kind of comment can make using the code much easier.

Summary: API comments are necessary to using the code.

6. Comments are Living Parts of the Code

This is probably the hardest guideline to follow.

When any piece of code is changed, you need to read and understand any associated intent comments. If the code has changed to violate the original intent, the comment must be modified to match.

Any time the comments and the code diverge, the comments become worse than useless. Not only does the invalid comment make this code harder to understand and maintain, it undermines the use of every comment elsewhere in the system. Worse, it leads to a distrust of all comments, even those in other code.

Summary: Comments must be maintained.