About the author

Tyler Adams joined the PullRequest reviewer network in 2020. Tyler has developed software and led engineering teams at a number of companies in New York and the Bay Area including Square, Pure Storage and Two Sigma.

Be sure to follow Tyler on Twitter @canardivore

For those who may not be familiar, code comments are non-functional lines of code used to communicate information to people who read it.

These can be used for a variety of purposes such, as leaving a reminder to change something in the future or explaining why code may appear to be unusual to the reader. In this post, I’ll focus on how to write a great comment for the latter.

A good comment tells you something that you want to know and you wouldn’t know without the comment. In practice, this means explaining weird looking code by bringing in outside context.

Let’s use a concrete example:

You already know it’s a cat. You don’t want to know the cat is a cat. Anybody can figure out that the fluffy thing with two eyes, pointy ears, and a tail is a cat.

If your cat is in your house, is it surprising that it’s there? No. So should your cat have a comment? No.

But what if there’s a strange cat in your office? That’s weird. Why is there a cat in the office? Dogs, sure. But a cat? People don’t bring their cat to the office. You’re intrigued. You want to know why there’s a cat here.

As you get closer, you see the cat has a comment:

// I'm in the office because I'm chasing away the mice: https://bug-tracker/BUG-001.

Oh, okay, all is well. You don’t have any questions.

The above comment is good. It’s really good. To help explain how good it is, I’m going to make it worse.

Slightly worse

// I'm in the office because I'm chasing away the mice.

Is it the same mouse problem as the one the mouse traps are for? Are there still mice in the office?

Even worse

// Chasing away the mice.

Same questions as the above comment. Also, it’s not clear what the implication of “chasing away the mice” is, so there’s a good chance it will be misinterpreted. Maybe it’s to explain why the cat shouldn’t be petted? i.e. “Don’t pet me because I’m chasing away the mice.”

Much worse

// I'm in the office.

If it’s in the basement, at least I know it shouldn’t be in the basement. But, still I want to know why it should be in the office.

So, after all of that, we see what makes a good comment. Four things:

• A good comment points out unusual code (there’s a cat in the office)
• A good comment makes explicit what is unusual (I’m in the office)
• A good comment makes explicit why the unusual code is present (chasing away the mice)
• A good comment provides more information about the “why” if appropriate (https://bug-tracker/BUG-007)

Be sure to follow Tyler on Twitter @canardivore