Are You Writing Useless Comments in Your Code?

Quality code usually comes with good comments that help us understand it better. But what makes a comment good, and when should you write one?

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

When you write the code you have a lot of information in your head. When someone else reads it — or you a few months later — that information is gone, and all that remains is the code.

What not to comment

A comment takes time and attention away from the code itself, so it has to earn that cost. These do not:

// User class definition
class User {
  // Constructor
  constructor() {}

  // Get user's first name
  getFirstName() {
    return this.firstName
  }

  // Set user's age
  setAge(age) {
    this.age = age
  }
}

Don't comment on facts that can be derived quickly from the code itself.

Don't comment just for the sake of it. Other developers should understand your intent from the code.

Don't comment bad names. A comment is not a fix for a bad name — fix the name.

// Replace encoded characters in a string
function cleanString(string) { ... }

Since all it does is decode a string, a self-documenting name like decodeString removes the need for the comment entirely.

What to comment

A lot of good comments come from simply writing down a few words of your thought process. That information is otherwise lost forever.

Write down your thought process:

// This function shouldn't have await since we don't need the result.

// This call might time out. That's OK since the data will be resent
// in the next invocation.

Without these, a reader might think there is a bug and waste time trying to reproduce it. A comment can also carry an idea for improvement:

// This class is getting too big. Maybe we should split out a subclass.

Comment the flaws. Finding a flaw is often more time-consuming than fixing it, so mark what you know. Common markers:

  • TODO — something that needs doing
  • HACK — code customized for a specific case
  • FIXME — a known issue
  • NOTE — be aware of something

Comment your constants. There is usually a reason behind a specific value:

// Set to 8 — we hit concurrency problems with more workers.
const NUM_OF_WORKERS = 8

// Reasonable limit; nobody buys more than 100 items. Safe to change later.
const MAX_CART_SIZE = 100

Some constants — SECONDS_IN_AN_HOUR — are clear enough on their own. Use common sense.

Put yourself in the reader's shoes

Anticipate likely questions. Where the code will make a reader think "what?" or "why?", answer in advance:

function clearArray(array) {
  array.length = 0
}

Why not array = []? Because that creates a new array and leaves existing references pointing at the old one. Setting length = 0 mutates the array in place, so all references see the change.

Explain the big picture. New team members struggle to understand how data flows through the system, where the entry points are, and what the expected output is — and the person who designed it usually skips those comments. Keep them short; a few well-chosen sentences are enough. In-depth documentation belongs elsewhere.

Summary

A comment's purpose is to help the reader know what the writer knew at the time. Comments should be short but useful, giving insight into what the code does and why.

  • Don't comment: facts, or fixes for bad names.
  • Do comment: insights about the code, flaws and known bugs, the reasoning behind constants.
  • Keep in mind: which parts are unclear, surprising behavior, the big picture.

Originally published on Medium.