A year ago, I took over a codebase I didn't write. It was vibe-coded — you could tell. Logic scattered across files, inconsistent naming, and comments. Everywhere.
Above every method, inside every loop, explaining things the code was supposedly already saying.
I rolled my eyes and started deleting them.
Fast forward to today. I pair program with AI almost daily and I wonder — should AI-generated comments help me understand quickly generated code, or do they help the AI too?
Comments as anti-pattern
Robert C. Martin was clear about it in Clean Code — a comment is a failure. If your code needs a comment to be understood, you didn't write it clearly enough.
The goal is self-documenting code — names so expressive, structure so clean, that the intent is obvious without explanation.
It's a principle that shaped a generation of developers. And for good reason. We've all seen the damage bad comments do:
// increment i by 1
i++;
// get user
var user = GetUser(id);
These comments add noise, not signal. Worse, they rot. Code gets refactored, comments don't. Now you have documentation that actively misleads anyone reading it — including the AI tools that consume it.
The traditional argument holds. Most comments are bad comments.
Comments, comments everywhere
The project had been built fast, by someone leaning heavily on AI generation. The comments weren't thoughtful — they were everywhere, auto-generated, verbose. Things like:
// This method processes the order and saves it to the database
public async Task ProcessOrderAsync(Order order)
{
// Validate the order first
await ValidateAsync(order);
// Save to database
await _repository.SaveAsync(order);
// Publish event to notify other services
await _eventBus.PublishAsync(new OrderProcessedEvent(order.Id));
}
My instinct was — most of this is noise. The method name already says ProcessOrderAsync. The variable names already tell you what's happening. The comments are just... the code, again, in English.
I cleaned them up. And I felt good about it.
Contextual comments make sense
I use Claude daily now. And at some point I caught myself wondering: does AI actually perform better in a well-commented file? Not just more pleasant to work with — but measurably better suggestions?
I started paying closer attention. Here's a concrete example that kept coming up. Two versions of the same method signature:
// Version A - no comments
public async Task<Result> HandleAsync(CreateOrderCommand command)
// Version B - one intent comment
// Validates business rules before persisting. Does NOT publish events —
// caller is responsible for dispatching domain events after success.
public async Task<Result> HandleAsync(CreateOrderCommand command)
When I ask AI to add error handling to Version B, it respects the constraint. It doesn't add event dispatching inside the method. With Version A, it sometimes does — because it doesn't know the rule.
That comment isn't explaining what the code does. It's explaining why it's structured the way it is, and what it deliberately doesn't do. That's information that can't live in a method name.
So who are comments actually for now?
When Uncle Bob wrote Clean Code, the only reader of your comments was a human developer. The argument was: if you need a comment, you failed to communicate through code. Write better code instead.
But today, your code has a second reader: the AI tools.
You work with AI every day. And AI doesn't read code the way humans do. It reads context. It looks for signals about intent, constraints, and decisions that aren't visible in syntax.
A well-placed comment isn't noise to an AI pair programmer — it's context it can actually use.
Research backs this up from two directions. A 2024 study published at ACL, Code Needs Comments: Enhancing Code LLMs with Comment Augmentation, found that LLMs trained and tested on commented code consistently outperformed those working with uncommented code. And a 2025 code review study tested GPT-4o and Gemini with and without contextual descriptions alongside code — the presence of context measurably changed the quality of the AI's output.
What vs. why
After a year of this, my working rule has shifted — not reversed.
Bad comments explain what the code does. The code already does that. Good comments explain why it does it that way, what constraints it's operating under, and what it deliberately avoids.
// BAD - explains what, code already shows this
// Loop through orders and calculate total
foreach (var order in orders)
{
total += order.Amount;
}
// GOOD - explains why, code can't show this
// We intentionally skip cancelled orders here.
// Cancelled amounts are handled separately in the reconciliation report
// to avoid double-counting with the refund pipeline.
foreach (var order in orders.Where(o => o.Status != OrderStatus.Cancelled))
{
total += order.Amount;
}
The second comment survives refactoring. It carries information that no amount of clean naming can convey. And it gives your AI pair programmer the context it needs to not introduce a bug the next time it touches that loop.
Conclusion
I still think most comments are anti-patterns. I still delete the ones that just narrate what the code does. I still believe that if you need three sentences to explain a method, the method probably needs to be broken up.
But I've stopped treating all comments as a failure. Some comments are the only place to record a decision — a constraint that emerged from a bug, a rule from the business, a reason why the "obvious" refactor would break something in production.
Those comments aren't admissions of defeat. They're institutional memory.
And in an era where I'm handing chunks of my codebase to an AI and asking it to extend them, that memory matters more than it used to.
The vibe-coded project I inherited? Still full of bad comments. But somewhere in that noise, there were a few that made the work easier. I wish I'd been more careful about which ones I deleted.
Do you write comments for the AI, for your future self, or are they still mostly noise in your codebase? I'm genuinely curious where other developers have landed on this.
Top comments (0)