Stop Writing Comments: Why Senior Devs Hate "Stale Lies"

#beginners #cleancode #javascript #career

Stop Writing Comments: Why Senior Devs Hate "Stale Lies"

I want you to open the last Pull Request you submitted.

Find a block of code where you wrote a comment. Now, read the code. Then read the comment.

Does the comment explain what the code is doing?
(e.g., // Loop through the array or // Check if user is valid)

If the answer is yes, delete it.

We are taught early in our careers—often by bootcamps or university professors who haven't shipped production code in a decade—that "Good code is well-commented code."

This is a lie.

In the real world, comments are not helpful guideposts. They are often failures.

The "Apology" Comment

When you feel the urge to write a comment explaining what a block of code is doing, you are usually apologizing for the fact that your code isn't clear enough on its own.

You are writing:

// Check if the user is eligible for the senior discount
if (u.age > 65 && u.s === 'active') { ... }

You are apologizing for naming your variable u instead of user. You are apologizing for using a magic string like 'active'. You are forcing the reader to read the English comment because the JavaScript is too cryptic.

The Pro Move? Don't apologize. Fix the code so the comment becomes redundant.

The Danger of "Stale Lies"

Here is the darker truth about comments: Code changes. Comments often don’t.

We fix a bug. We update the logic. We change the requirement. But we forget to update the little grey line of text above it.

Six months later, "Future You" comes back to the file. You read the comment. You trust the comment. But the comment is now a lie. The code does one thing, but the comment says it does another.

I have spent days debugging systems because I trusted a comment that became a "Stale Lie" three years ago.

Code is the truth. Comments are hearsay.

The "What" vs. The "Why"

Does this mean you should never write a comment? No. But the rules are strict.

A Coder writes comments to explain Syntax (The "What").
A Professional writes comments to explain Business Logic (The "Why").

We know i++ increments i. Don't teach us syntax. Tell us why we are doing something weird.

The Code

Let’s look at a classic "Junior Trap" where we use comments to patch over bad naming, versus the "Pro Move" where the code speaks for itself.

// Before: The "Captain Obvious" Approach

This code is full of noise. The comments are just repeating what the code does, or explaining mysterious variables.

// Calculate the final price
// 'p' is the price, 't' is the tax
const val = p + (p * t);

// Check if we should apply the discount
// If the user role is 1 (Admin), they don't get a discount
if (user.role === 1) {
  return val;
}

// Otherwise apply 10% off
return val * 0.9;

// After: The Self-Documenting Standard

We removed the "What" comments. We renamed variables to reveal intent. The only comment left explains a weird business rule that you couldn't guess just by reading the code.

const totalWithTax = basePrice + (basePrice * taxRate);

const isAdmin = user.role === ROLES.ADMIN;

// BUSINESS RULE: Admins are not eligible for discounts 
// because their base accounts are already subsidized.
if (isAdmin) {
  return totalWithTax;
}

const DISCOUNT_MULTIPLIER = 0.9; // 10% off
return totalWithTax * DISCOUNT_MULTIPLIER;