Dario Cuevas

Posted on Oct 27 • Originally published at dariocuevas.com

Why I Changed My Mind About Code Comments

#codecomments #cleancode #ai

Why I Changed My Mind About Code Comments

🎬 The Awakening — When Your Own Code Bites Back

I still remember the day in 2011 when I found a piece of particularly nasty code in our codebase. I checked git blame. It was me. A year earlier.

This moment crystallized everything I'd learned since leaving consultancy in 2010. In consulting, you write code and move on. Someone else's problem. But in a product company? That code is yours. You'll maintain it, extend it, and curse it at 2 AM when production goes down.

That's when a senior engineer handed me Clean Code by Robert C. Martin. I devoured it. The book promised redemption through better naming, formatting, testing, and refactoring.

At its heart was a radical idea: comments are failures. If your code needs comments, you've failed to make it self-documenting.

I became a fanatic.

🧹 The Clean Code Years — When Comments Became the Enemy

From 2010 to 2014, I practiced what Robert Martin preached with religious fervor: kill the comments.

Instead of writing // Calculate the total price including tax and discount, I'd extract a function called calculateFinalPriceWithTaxAndDiscount(). The function name became the comment.

When I needed to explain a complex algorithm, I'd split it into smaller, well-named functions: validateUserInput(), processPaymentTransaction(), sendConfirmationEmail(). Each name was documentation embedded in code.

I had a killer argument against comments: they get outdated. Comments that lie are worse than no comments. Let the code be the single source of truth.

My code became cleaner. Functions smaller. Variable names ridiculously long but descriptive. I felt like a craftsman who'd mastered the technique.

But there was a nagging feeling I couldn't shake...

💡 The Philosophy Shift — When Everything Changed

Then I read A Philosophy of Software Design by John Ousterhout. My world turned upside down again.

Ousterhout directly challenged Clean Code: "Comments do not represent failures. The information they provide is quite different from that provided by code, and this information can't be represented in code today."

Wait. What?

The key insight: Comments are fundamental to abstractions. Without comments, you can't hide complexity. If users must read the code to use a method, then there is no abstraction—all complexity is exposed.

Here's a real example of my evolution:

Before (Clean Code approach):

function calculateTimeRemaining(startDate, endDate, excludeWeekends, holidays) {
  // Function name tells WHAT, but not WHY
}

After (Philosophy of Software Design approach):

/**
 * Calculates business days remaining for project deadline.
 * 
 * We use business days because our SLA commitments to customers
 * are based on business days. Weekend exclusion handles our 24/5
 * support model. Holidays vary by region.
 */
function calculateTimeRemaining(startDate, endDate, excludeWeekends, holidays) {
  // Implementation...
}

The function name tells you what. The comment tells you why, the business context, and the assumptions. Both are essential.

Ousterhout demolished Martin's solution of extracting functions with longer names: "This results in names like isLeastRelevantMultipleOfNextLargerPrimeFactor. Even with all these words, names like this are cryptic and provide less information than a well-written comment."

I suddenly saw all those ridiculously long function names for what they were: a workaround to avoid writing one clear sentence.

The synthesis I reached: Robert Martin was right about 80% of things. Clean code, expressive naming, small functions—all essential. But comments aren't failures. Bad comments are failures.

My current practice:

Short, internal functions: Minimal comments. The code speaks.
Complex functions: Comments explain the why and business context.
Public APIs: Comments are mandatory. They define the abstraction.
Tricky workarounds: Comments are essential. They save hours of confusion.

🤖 The AI Era — Why Comments Matter More Than Ever

Now we're in 2025, and there's a new player: AI coding assistants.

I use Claude Code with a claude.md file in my projects. Here's what I discovered: good comments make AI dramatically more effective.

GitHub Copilot, Claude, and other AI assistants use comments as crucial context. They parse not just syntax but interpret comments to understand intent and generate better suggestions.

This changes everything. We're not just writing comments for humans—we're writing them for AI assistants that help us code faster.

And let's remember: code is read far more than it's written.

Robert Martin himself said it: "The ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code."

In my 15+ years, this rings absolutely true. I spend my days understanding code before changing it, fixing bugs, reviewing code, investigating incidents, and onboarding team members. We're not creating greenfield projects daily—we're maintaining, extending, and evolving existing systems. All of that requires reading code.

If code is read 10x more than it's written, making code easier to read has a 10x multiplier on productivity. Good comments make code dramatically easier to read.

📝 What Good Comments Look Like

• Explain the "Why," Not the "What" — Code shows what. Comments explain why, what business logic it serves, and what assumptions it makes.

• Capture What Code Cannot Express — Document context, constraints, trade-offs, and decisions invisible in code.

• Stay Close to the Code — Comments next to what they describe stay updated. Avoid distant documentation.

• Don't Duplicate the Code — If your comment restates the obvious (// increment counter), delete it.

• Document Edge Cases and Gotchas — Weird workarounds? Input assumptions? Threading constraints? Comment them!

• Provide Examples — One input/output example beats paragraphs of abstract description.

• Keep Them Updated — Change code, update comments. Make it part of code review.

• Write During Development — Don't leave for later. Write when context is fresh.

• Use Standard Formats — JSDoc, Javadoc, Python docstrings—use your language's conventions.

The Bottom Line

After 15 years and two philosophical earthquakes:

Clean Code is right: Write expressive code with clear names and good structure.

Philosophy of Software Design is also right: Comments capture essential information code alone cannot express.

In the AI era: Comments aren't just for humans. They're context for AI assistants. No excuse for skipping them.

The best code isn't comment-free. The best code uses comments wisely—where they add value, explain context, and make code dramatically easier to understand.

Robert Martin and John Ousterhout aren't enemies. They're two perspectives on the same problem.

Write clean code. Use good names. Keep functions small. And write clear, valuable comments that explain what the code cannot.

Your future self—and your AI coding assistant—will thank you.

What's your take? Have you evolved your philosophy over the years?