Skip to Main Content
The Art of Readable Code
book

The Art of Readable Code

by Dustin Boswell, Trevor Foucher
November 2011
Intermediate to advanced content levelIntermediate to advanced
206 pages
4h 32m
English
O'Reilly Media, Inc.
Content preview from The Art of Readable Code

Chapter 6. Making Comments Precise and Compact

image with no caption

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 ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.
Start your free trial

You might also like

Five Lines of Code

Five Lines of Code

Christian Clausen
The Art of Clean Code

The Art of Clean Code

Christian Mayer

Publisher Resources

ISBN: 9781449318482Errata Page