The Matrix: Writing Code That Doesn't Need Comments

The Quest Begins (The "Why")

I still remember the first time I opened a pull request that looked like a novel written in hieroglyphics. The function was called processData, it accepted a flag named mode, and inside there were nested if blocks that checked the flag against magic numbers like 3, 7, and 42. The only clue to what any of it meant was a single line comment at the top:

// mode: 1 = upload, 2 = download, 3 = transform

I spent half an hour tracing through the code, scribbling on a notepad, and still felt like I was decoding a secret message. When I finally asked the author, they shrugged and said, “Oh, the comment explains it.”

That moment stuck with me. Comments are a crutch. When we rely on them to tell the story of our code, we’re essentially admitting the code itself isn’t clear enough to stand on its own. And the worst part? Comments rot. They get outdated, they lie, and they become the very thing that misleads the next person (or future you) who has to touch the file.

So I set out on a quest: write code so expressive that comments become unnecessary, not because I’m lazy, but because the code itself tells the whole story.

The Revelation (The Insight)

The best practice that changed everything for me is naming with intent and breaking work into tiny, single‑purpose functions. In other words, let the names do the talking.

When a function name reads like a sentence—validateEmailAddress, calculateTotalPrice, fetchUserProfile—you instantly know what it does without needing a side note. When a variable is called userIsAuthenticated instead of flag, the condition if (userIsAuthenticated) reads like plain English.

Why does this work?

1. Cognitive load drops – Your brain doesn’t have to translate a comment into meaning; it just reads the code.
2. Self‑checking – If you rename something and the code no longer reads naturally, you’ll notice the mismatch immediately.
3. Documentation stays in sync – No extra*sync* with the code because it is the code. No separate file to forget to update.

The side effect? You start writing smaller functions. A function that does one thing and does it well is easier to name clearly, easier to test, and easier to reuse.

Wielding the Power (Code & Examples)

Let’s look at a common scenario: processing an order with a discount coupon. Here’s the “before” version that leans heavily on comments:

// applyCoupon: returns the discounted price
function applyCoupon(price, coupon) {
  // coupon must be a valid object with code and percentOff
  if (!coupon || !coupon.code || !coupon.percentOff) {
    // invalid coupon, return original price
    return price;
  }
  // check if the coupon is expired
  const now = Date.now();
  if (coupon.expiresAt && now > coupon.expiresAt) {
    // expired coupon, no discount
    return price;
  }
  // calculate discount amount
  const discount = price * (coupon.percentOff / 100);
  // ensure we don't discount more than the price
  const finalPrice = price - discount;
  return finalPrice < 0 ? 0 : finalPrice;
}

What’s wrong?

• The function does multiple things: validation, expiration check, math, and clamping.
• The comments are basically repeating what the code already says, but they’re easy to ignore or forget to update.
• If someone changes the shape of the coupon object, the comments become misleading instantly.

Now the “after” version, where the names and small functions do the work:

function applyCoupon(price, coupon) {
  if (!isValidCoupon(coupon)) {
    return price;
  }
  if (isCouponExpired(coupon)) {
    return price;
  }
  const discountAmount = calculateDiscount(price, coupon.percentOff);
  return clampPrice(price - discountAmount, 0);
}

// ---- tiny, clearly named helpers ----
function isValidCoupon(coupon) {
  return coupon && coupon.code && coupon.percentOff !== undefined;
}

function isCouponExpired(coupon) {
  return coupon.expiresAt && Date.now() > coupon.expiresAt;
}

function calculateDiscount(price, percentOff) {
  return price * (percentOff / 100);
}

function clampPrice(value, min) {
  return value < min ? min : value;
}

What changed?

• applyCoupon now reads like a story: if the coupon isn’t valid, return the price; if it’s expired, return the price; otherwise calculate the discount and clamp the result.
• Each helper does exactly one thing, and its name tells you what that thing is.
• No comment is needed because the code itself explains the intent.
• If tomorrow the coupon shape changes, you’ll only need to adjust isValidCoupon and the compiler (or tests) will immediately point out any mismatched usage.

The Trap to Avoid

A common pitfall is to replace a comment with a misleading name, thinking you’ve solved the problem. For example:

function applyCoupon(price, coupon) {
  // we think this is the discount
  const x = price * 0.1;
  return price - x;
}

The variable x tells you nothing, and the comment is now a lie if the discount ever changes from 10 %. The fix? Give the variable a meaningful name (discountAmount) and, if the rate might vary, pull it out as a parameter or a constant with a clear name (DEFAULT_DISCOUNT_PERCENT).

Why This New Power Matters

When your code speaks for itself, you gain a handful of super‑powers that ripple through the whole team:

• Faster onboarding – New teammates can read a function and grasp its purpose in seconds, not minutes of comment‑hunting.
• Fewer bugs – Misunderstandings caused by outdated comments disappear. The code is the single source of truth.
• Refactoring confidence – You can rename a function or variable knowing that the name itself is the contract; if the name no longer fits, you’ll see it immediately.
• Cleaner diffs – Pull requests show real logic changes, not just comment edits. Reviewers spend time on what matters.

Think of it like clearing a foggy windshield. Once you can see the road ahead, you drive faster, safer, and with more enjoyment.

Your Turn

I challenge you to take a function you’ve written recently that leans on a comment for clarity. Rewrite it using only expressive names and small, single‑purpose helpers. Notice how the comment disappears—not because you removed it, but because it’s no longer needed.

Share your before/after snippets in the comments below, and let’s celebrate the joy of code that needs no annotation. Happy coding!