Writing Useful Comments in Code

Posted on March 21, 2021

What makes for useful comments in code?

Good comments should be written with their audience in mind, and should convey new and useful information. They should make the life easier for the person reading them.

Audience

Sometimes commenting code can be about as pleasant and useful as waiting in line at the DMV. I’m thinking of the Javadoc-style comments, where you have to document every argument, return value, and exception.

/**
 * Adds two values together
 * @param a the first value
 * @param b the second value
 * @return a and b added together
 */
public int add(int a, int b);

These comments often feel pointless because they are the wrong tool for the job. They go into detail that’s probably unnecessary and tell you things you probably already know. While that style can be useful for libraries used by thousands of developers, we usually are writing code with a smaller audience. Our comments will be read by just a few other teams, or perhaps just our team, or even just ourselves. We don’t need to drive a semi truck to get the groceries.

When you think about who the audience for the comments is, you might realize that they’ll already know everything you were going to say in that comment. In that case, it’s fine to skip writing that comment and direct your effort somewhere else where it will be more useful.

You audience will appreciate it when you write comments that tell them new things that they find useful. You can warning them about a common pitfall, give context behind a decision, or leave hints to help them understand the code.

A comment should use the easiest to follow, least technical language it can without being inaccurate. It’s not an academic paper; it’s an explanation to your fellow developer.

Write comments for the sake of the person reading them, not for the sake of writing comments.

New and useful

Comments should tell the reader something that they don’t already know, but would find useful to know. Fortunately, there’s a lot of different things you can say that a reader will find useful.

It’s useful for comments to explain why. You can see for yourself what the code does, but without comments you can only guess at why that’s the right thing to do.

My personal favorite comments in code are ones that explain why something is different from what you’d expect. Those comments answer a question you’ll have about the code right as you have it, and show that the author was thinking ahead (and didn’t just make a mistake). Any time something is surprising or prone to misinterpretation, that’s a great opportunity for a useful comment.

Sometimes there’s a process people working on the code will need to follow. Maybe you need to deploy one part of the change before merging another part, or perhaps you should give customer support a heads-up before your change goes out. If the process has to do with one particular area of the code, it’s useful to write that process (or link to it) in a comment above that part of the code.

Comments can act as a shortcut. They’ll convey something the readers technically could have figured out themselves, but much less time and effort. A good comment might replace a half hour of digging with 5 seconds of reading. Potential shortcuts include:

A link to where to find a design document.
A simple summary of what a complicated-looking function actually does (e.g. “this skips any entries we can remove without impacting the result”).
A pointer to somewhere else in the code the reader should look at.
A description of how the classes fix together (e.g. “plans contain a single step because steps can contain other steps in the composite pattern”).
A name for what is going on (e.g. “this is basically the visitor pattern”).

I also like TODOs in code. Sometimes they can feel like a sign of a messy codebase, but (when used in moderation) they give really useful context. TODOs can tell the reader if this structure was intentional, or just a quick hack. They can give context on what is temporary, or what you might want to do differently when writing similar code.

Some TODO comments can be just noise. If they just say TODO: Fix this, that doesn’t helper the reader know what needs to be fixed or how it should be fixed. A comment like TODO: Use the new database connection type is far better - it tells you what to do and gives some hints about the rest of the codebase.

Next time you are reading some unfamiliar code, pay attention to the comments. Which do you find useful? What do you wish a comment would tell you?