You’ve probably felt the twitch of annoyance. You ask Claude to write a function, and it returns a pristine block of code—completely suffocated by a dense web of verbose, painfully obvious comments. Every variable explained. Every loop justified. It feels like reading a textbook written by a paranoid intern.
Recently, a developer on Hacker News pointed out this exact friction. Their “meat-based engineers” were furious, demanding that Claude be explicitly instructed to never leave comments unless absolutely necessary. It’s a familiar battle cry in software engineering: real programmers write self-documenting code. Comments are clutter. Comments are security risks. We’ve all been taught this in school.
But what if we are completely missing the point?
We spent decades teaching junior developers to write self-documenting code, only to panic when our AI assistants started writing self-documenting code for each other.
Here is the twist that most engineers are missing right now: Claude’s verbose comments are not a stylistic flaw. They are a functional byproduct of its training on human codebases, yes, but they have rapidly evolved into something else entirely. They are a coordination mechanism. The real tension here isn’t between good code and bad code; it’s between human norms of minimalism and the AI’s emergent need to maintain context across agent chains.
Think about it. When you write a comment, you are addressing a future human reader. You are trying to bridge the gap in their understanding. But when an AI agent writes a comment, who is it talking to? It’s not talking to you. It is leaving breadcrumbs for the next LLM instance that gets dropped into the workflow to debug, refactor, or extend that exact file.
The comments aren’t a bug in the system; they are the emerging language of a multi-agent workforce.
We are entering the era of agentic loops. Your codebase is no longer just a set of instructions for a machine to execute; it is a workspace where multiple AI agents will collaborate, hand off tasks, and pick up where the last instance left off. For an AI, reading a heavily commented file is like reading a brief. It instantly establishes the context, the intent, and the boundaries without needing to re-infer the entire architecture from raw syntax.
Yes, it violates your professional sensibilities. You want clean, elegant, minimalist code. But your expectations are anchored to a human-centric paradigm. You want the tool to adapt to you. But the tool is optimizing for a future where the primary reader of the codebase isn’t a human engineer, but another AI.
You aren’t the audience for your code anymore. You’re just the landlord.
So, the next time Claude leaves a paragraph explaining why it used a for-loop instead of a while-loop, don’t immediately delete it or scold the prompt. Ask yourself if you are looking at an artifact of a new machine-first readability standard. You can fight it, strip the comments out, and force the AI to speak only to you. Or you can step back, embrace the friction, and realize you are watching the birth of inter-agent communication right in your IDE.
FAQ
Q: Doesn't this just bloat the codebase and make it harder for humans to read?
A: Yes, it temporarily clutters the human reading experience. But as IDEs evolve, we will likely see comment-toggling features that hide AI-to-AI context from human view, separating human documentation from agent breadcrumbs.
Q: How should I adjust my AI coding workflow then?
A: Stop aggressively prompting the AI to strip comments. Let it document its logic. If you need a cleaner view for human review, use your IDE's folding features or write a quick script to strip comments before final human review, but leave them for agent-driven refactoring.
Q: Is human readability going to become entirely obsolete?
A: Not obsolete, but secondary. Code is shifting from a human-machine interface into a machine-machine interface. Humans will increasingly act as reviewers and architects rather than line-by-line authors, reading AI-generated summaries rather than raw syntax.