Writing Good Code Comments

I discuss why, when, and how you should write comments in your code.

During my career I have received conflicting advices about code comments. I recall a tech lead telling me I should comment everything and another telling me I should never comment because that is a code smell. Of course both were wrong, and since I’m right, I will now explain how to properly comment your code.

Documentation comments and code comments

I make a distinction between documentation comments, written for an external tool (such as Javadoc or rustdoc), and code comments, written for developers reading the code.

Documentation comments target users of the code and describe how to use it. They are great. You should write them whenever they are desirable (such as when writing a library). This article will not cover this type of comments. They are highly dependent on the language, and most tools have great recommendations on how to write documentation. You should follow these guidelines.

Code comments serve another purpose: they target developers to help them understand the code. Making the code understandable by humans is one of the most important goals of a software engineer, and code comments is one way to achieve it. Let’s see why, when, and how to write them.

When should you write code comments?

Depending on who you ask, the answer is “always” or “never”. Since you ask me, I think you should write code comments whenever the code is not self-explanatory and you have no other means of improving it.

The debate about code comments and code smell comes from a confusion on cause and correlation. There is a correlation between complex code and comments, because complex code requires more explanations. Since simplicity is a desirable trait, that makes code comments undesirable. This is a fallacy because you could have a complex code without comments, which is probably the worst situation.

More importantly, some complexity is unavoidable: sometimes you must optimize the code, sometimes there is a bug you cannot fix (e.g., a bug in a dependency), sometimes you must ship and cannot write a time-consuming refactoring. All these reasons, whatever their merit, could prevent you from writing simple and self-documenting code.

You should try to find other ways to convey meaning and remove complexity, but if that is not achievable, do write code comments.

Why not use comments more liberally? Because comments make maintenance harder. When the code is updated, it is very easy to forget updating the corresponding comments. A code with a lot of comments will become more difficult to maintain, and when too many comments are obsolete the code will be more difficult to understand

Adding meaning with good names

A good way to avoid using comments is to properly name functions and variables. No need to be creative, do not try to be funny. Write boring names. Be explicit. Write very long names if required.

// computes the horizontal offset
fn hoff(x: i32) -> i32 {
    // add header column width
    x + 32
}

const HEADER_COLUMN_WIDTH: i32 = 32;

fn compute_horizontal_offset(x: i32) -> i32 {
    x + HEADER_COLUMN_WIDTH
}

Adding meaning by extracting functions

A function is not only useful to reuse a piece of code, but also for naming what it does. Function names are usually better maintained than code comments.

fn rename_user(id: Uuid, new_name: String) {
    // load user
    …

    user.name = new_name;

    // save user
    …
}

fn rename_user(id: Uuid, new_name: String) {
    let user = load_user(id);
    user.name = new_name;
    save_user(user)
}

fn load_user(id: Uuid) -> User { … }
fn save_user(user: User) { … }

Dos and don’ts

Here are some guidelines for writing good code comments.

Dos

• Do keep it short and simple. Just like your code, good comments are easy to read and understand.
• Do add context. If there is a non-obvious reason the commented piece of code needs clarification, you should explain it. The goal here is to prevent someone who does not see the whole picture from trying to “simplify” the code and accidentally add a regression.
• Do give improvement guidelines. If you know a way to improve the code but did not have the time to do it, or if an improvement relies on future work (e.g., a bug fix or a refactoring), explain it. This way, someone reading the comment in the future will know if they can rewrite the code and remove the comment.

Don’ts

• Don’t describe trivial instructions. Comments in production code should not try to teach people how a language or framework works. If you need to teach junior developers, find a more appropriate way to do it. Code comments need too much maintenance.
• Don’t write joke comments. We’ve all read them, but I think they’re bad and you are not helping anyone by trying to look clever or funny.
• Don’t shame other developers. Comments are not a proper way to vent your frustration, and it’s never appropriate to be mean to someone for the code they wrote. You do not always know the constraints and difficulty they faced.
• Avoid referencing other sources. It’s fine to add a link to a Wikipedia page, but avoid bug numbers or link to a bug tracking tool. The code will probably outlive any external tool or personal blog.

I used to avoid comments at all cost. Now I write more comments, but still feel like I should first try to make comments unnecessary.