The Art of Readable Code

Chapter 6. Making Comments Precise and Compact

The previous chapter was about realizing what you should be commenting. This chapter is about how to write comments that are precise and compact.

If you’re going to write a comment at all, it might as well be precise—as specific and detailed as possible. On the other hand, comments take up extra space on the screen, and take extra time to read. So comments should also be compact.

Key Idea

Comments should have a high information-to-space ratio.

The rest of the chapter shows examples of how to do this.

Keep Comments Compact

Here’s an example of a comment for a C++ type definition:

// The int is the CategoryType.
// The first float in the inner pair is the 'score',
// the second is the 'weight'.
typedef hash_map<int, pair<float, float> > ScoreMap;

But why use three lines to explain it, when you can illustrate it in just one line?

// CategoryType -> (score, weight)
typedef hash_map<int, pair<float, float> > ScoreMap;

Some comments need three lines of space, but this is not one of them.

Avoid Ambiguous Pronouns

As the classic “Who’s on First?” skit illustrated, pronouns can make things very confusing.

It takes extra work for the reader to “resolve” a pronoun. And in some cases, it’s unclear what “it” or “this” is referring to. Here’s an example:

// Insert the data into the cache, but check if it's too big first.

In this comment, “it” might refer to the data ...