Writing Code That Doesn't Need Comments: The Matrix Approach

The Quest Begins (The "Why")

Honestly, I used to think comments were the safety net that kept my future self from falling into a pit of “what does this even do?” I’d slap a // TODO: explain this later on every tricky block, convinced that the more words I dumped beside the code, the clearer it’d become.

Then came the day I inherited a legacy service riddled with comments that were outright lies. The function calculateTax had a comment saying “Applies a 10 % discount for premium users”, but the code actually added a surcharge. I spent three hours chasing a bug that only existed because the comment was lying to me. I felt like Neo realizing the world he’d been told was real was just a simulation—except my simulation was a messy codebase and the red pill was a well‑named function.

That moment cracked my faith in comments. If they can rot, become outdated, or outright mislead, why rely on them at all? I started asking myself: What if the code could speak for itself?

The Revelation (The Insight)

The treasure I uncovered wasn’t a new framework or a fancy language feature—it was a simple, old‑school refactoring habit: replace a comment with an intent‑revealing function (or variable).

When you feel the urge to write a comment that explains what a block of code does, pause. Instead of writing the explanation, extract that block into its own function and give it a name that is the explanation. The code then reads like a story, and the need for a comment disappears.

Why does this work? Because names are part of the code’s contract with the compiler and, more importantly, with the next human who reads it. A well‑chosen name is checked by the compiler (you can’t call a function that doesn’t exist) and stays in sync with the implementation. A comment, meanwhile, is just free‑form text that the compiler ignores—so it can drift away unnoticed.

Wielding the Power (Code & Examples)

The Struggle: Comment‑Heavy Code

// Calculate the final price after applying the seasonal discount
function getFinalPrice(basePrice, isMember) {
  let discount = 0;
  // If it's winter season and the user is a member, give 15% off
  if (isMember && new Date().getMonth() >= 11 || new Date().getMonth() <= 1) {
    discount = basePrice * 0.15;
  }
  // Apply the discount
  return basePrice - discount;
}

Look at those comments. They’re trying to tell you what the if block does, what the discount variable represents, and what the final return means. But notice how the comment about the season is already a bit cryptic (>= 11 || <= 1) and could easily become outdated if the business changes the discount window.

The Victory: Self‑Documenting Code

function isWinterSeason() {
  const month = new Date().getMonth(); // 0 = Jan, 11 = Dec
  return month === 11 || month === 0 || month === 1; // Dec, Jan, Feb
}

function memberWinterDiscount(basePrice) {
  return basePrice * 0.15;
}

function getFinalPrice(basePrice, isMember) {
  const discount = isMember && isWinterSeason()
    ? memberWinterDiscount(basePrice)
    : 0;
  return basePrice - discount;
}

What changed?

• The comment “Calculate the final price after applying the seasonal discount” is now obvious from the function name getFinalPrice.
• The bulky seasonal check lives in isWinterSeason(), a name that tells you exactly what it returns—no comment needed.
• The discount calculation is isolated in memberWinterDiscount(), again speaking for itself.
• The main function now reads like a sentence: “If the member qualifies for a winter discount, subtract that discount; otherwise, subtract zero.”

If the marketing team later decides the winter discount should run from November to February, I only touch isWinterSeason(). The comment that used to live beside the if never existed, so there’s nothing to stale or contradict.

Common Traps to Avoid

1. Extracting too little – Don’t pull out a single line just to have a function; the new name must add clarity.
2. Leaving the comment behind – After you extract, delete the old comment. Keeping it defeats the purpose and can confuse readers.
3. Naming poorly – calc() or doStuff() are worse than a comment. Choose names that capture intent, not just mechanics.

Why This New Power Matters

When you stop leaning on comments and start letting names do the talking, a few magical things happen:

• Readability skyrockets – New teammates can follow the flow without constantly jumping back and forth between code and explanations.
• Refactoring becomes safer – Renaming a function is a compile‑time check; renaming a comment is a gamble.
• Documentation stays in sync – Because the explanation is the code, you never have to worry about a comment drifting away after a bug fix.
• You write fewer lines – Ironically, extracting a function often reduces visual clutter because the main routine becomes a high‑level narrative.

It’s like swapping a cluttered dungeon map for a clear, labeled path: you still know where the traps are, but you can walk through confidently without constantly checking the legend.

Your Turn, Adventurer

Give this practice a spin on a piece of code you’ve been meaning to clean up. Find a comment that explains what a block does, extract that block into a function (or constant) whose name is the explanation, and watch the comment disappear.

Challenge: Pick one function in your current project that has a comment longer than three lines. Refactor it using the technique above and share the before/after snippet in the comments—let’s see how clean we can make our codebases together!

Happy coding, and may your functions always be as clear as a Neo‑styled dodge in the Matrix. 🚀