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 5. Knowing What to Comment

image with no caption

The goal of this chapter is to help you realize what you should be commenting. You might think the purpose of commenting is to “explain what the code does,” but that is just a small part of it.

Key Idea

The purpose of commenting is to help the reader know as much as the writer did.

When you’re writing code, you have a lot of valuable information in your head. When other people read your code, that information is lost—all they have is the code in front of them.

In this chapter, we’ll show you many examples of when to write down that information in your head. We’ve left out the more mundane points about commenting; instead, we’ve focused on the more interesting and “underserved” aspects of commenting.

We’ve organized the chapter into the following areas:

  • Knowing what not to comment

  • Recording your thoughts as you code

  • Putting yourself in the readers’ shoes, to imagine what they’ll need to know

What NOT to Comment

image with no caption

Reading a comment takes time away from reading the actual code, and each comment takes up space on the screen. That is, it better be worth it. So where do you draw the line between a worthless comment and a good one?

All of the comments in this code are worthless:

// The class definition for Account
class Account {
  public:
    // Constructor
    Account();

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