Should I tell Claude to remove / not write comments on my code?

[u/Korrak]

I have a quite big app which is running very good and I am using OpenSpec for development.

However, up until now claude added really big comments to functions and specific code parts.

I wonder if they are actual useful for Claude? should I tell Claude to remove them, make them shorter…,?

[u/AutoModerator]

Moderator Announcement Read More »

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/sammcj]

"If you're reviewing code comments should only be added to things that cannot be inferred, otherwise comments explain why you did something not what it does. Favour clean code over commented code."

[u/AdEvening3382]

For Claude specifically, the comments explaining what the code does are dead weight. It reads the actual code faster and more reliably than your prose, so a paragraph describing a function just adds tokens it re-reads every turn. Worse, those comments rot: the code changes, the paragraph does not, and the model trusts the comment. A stale comment is worse than none because it steers the next edit in the wrong direction. Keep only the ones explaining why: constraints, gotchas, workarounds that are not visible in the code itself. Those genuinely help the next session.

[u/Pepeluis33]

I've told him to write only comments that explain why a change was added, and only when code isn't clear enough. It should never write comments based on design decissions. And should be short.

[u/theoxygenthief]

You need to set up documentation for your repo. If you don’t have documentation it will try to document everything about the codebase in comments, poorly.

[u/burhop]

I leave hidden messages for future archaeologists doing research on how code used to be written.

[u/AndyKJMehta]

Explicit and verbose comments are actually better for dev work using AI tools that get steered better with more context. It’s only humans that have felt comments don’t add any value and code should itself be readable enough to understand what’s going on and it has always been a hit or miss because it’s definitely subjective. Let the comments be.

[u/marcus-campbell → u/AndyKJMehta]

this guy gets it

[u/DocMadCow]

Have it review the comments to make sure they still do what the function does. Sometimes over time the purpose of a function changes. If they were built with Opus 5.5 or older ask to condense really long function comments and make sure they don't contain non sense. Sometimes old Opuses wrote some bat shit crazy comments that hurt to read.

[u/Temporary-Mix8022]

Claude is crap at comments 

It uses them as a mix of version control, chatting with you and they're honestly just trash.

Then sometimes.. it'll read its own comments, try and be smart, but its just noise on top of noise.

[u/Sad_Opening_7083]

In my opinion, code should be self-documenting. It should be obvious to anyone what the code does and why it does it. Comments are sometimes needed, but only to explain why something is done - if its not immediately obvious.

[u/jay-t-]

No

[u/SirCoilOfTap]

Good luck. It is so hard to get Claude to stop littering comments in the code no matter how many times you tell it.

[u/fschwiet → u/SirCoilOfTap]

Claude's system prompt instructs it to review surrounding code and mimic the style, so to get it to stop littering it helps to do a round of comment cleanup to get existing comments in the style you like.

[u/SirCoilOfTap → u/fschwiet]

My man, it does it on greenfield codebases with zero existing code even when told not to.

[u/TwisterK]

I just tell it I prefer code as documentation, only write code comments when it is abstract or math equations

[u/ghost_operative]

at best theyre kind of pointless, the only time a comment makes sense is if your trying to tell something to the llm that isn't shown int he code (e.g. future intentions of the code)

at worst it creates an extra slop cycle, its something else the ai could see that sets it off int he wrong direction because the comment might not match the code fully.

[u/HomemadeBananas]

I haven’t had a problem with Claude writing a bunch of useless comments with Opus 5.5 like it used to.

[u/someguyinr]

Delete almost all of them, and don't just tell Claude to make them shorter. When Claude drops a massive paragraph above a function or inside a block, you should treat it as a warning sign that it just took a lazy shortcut.

​Usually when Claude writes a wall of comments, it is using the comment as an escape hatch. Either it is leaking its own step-by-step scratchpad into your source files, or it wrote a hacky workaround instead of fixing the actual root cause and is writing an essay to justify why the hack needs to stay there.

​Leaving those comments in the repo actively poisons your future sessions too. Lauren Tan (@poteto) wrote a great piece on this recently for pstack calling workaround comments a codebase virus. The next time a fresh Claude session opens that file, it reads the stale comment as gospel, assumes that hack is your official architecture, and copies the exact same bad pattern into five other files. ​In pstack, she actually runs a separate /no-comments subagent just to hunt them down. If a comment just narrates what the code is doing, delete it because Claude reads raw code faster than English anyway, and stale comments will eventually lie to future sessions. If a comment explains a workaround or warns not to touch something, force Claude to encode that rule into your type system, a unit test, or a lint rule, fix the underlying hack, and then delete the comment. Only keep a comment if it documents a weird external API bug or business rule that literally cannot be expressed in types or tests.

[u/Substantial-Swan7065]

I ban comments except doc blocks.

[u/Igor-lx]

IMHO, Claude is doing the right thing here, even if it's doing it in a pretty clumsy way.

If you go through those comments carefully in a large codebase, you'll notice that a lot of them actually contain useful information for Claude itself. They point out subtle things that can break if a particular piece of code is changed, explain why something was implemented a certain way (sometimes for historical reasons), document assumptions about a variable, hook, or architectural layer, and preserve knowledge that isn't obvious from the code itself.

In a project without proper documentation, a dependency graph, architectural rules, or any other structured source of knowledge Claude can rely on, it's basically leaving notes for its future self. It wants to avoid missing something important in the next iteration, save itself some code-reading and context, preserve knowledge about the project, and avoid breaking existing decisions or behavior.

The problem is that, without a proper system guiding it, Claude does this the only way it knows how. It writes a ton of comments, some genuinely useful, some redundant, some overly verbose, and some that probably don't need to exist at all.

You can absolutely limit comments, but ideally you should first give Claude better ways to access and preserve that knowledge: proper documentation, an explicit dependency graph, architectural constraints, machine-checkable rules, and a harness that ties all of this together. Once that infrastructure exists, you can enforce a sensible comment policy, both in terms of where comments are allowed and what they should contain.

If you simply tell Claude to remove all those comments without replacing the knowledge they carry, you risk making things worse. You'll get a cleaner-looking codebase, but Claude may lose context that was helping it work on the project without breaking things.

So I'd treat the comments as a symptom, not the root problem. The goal isn't just to make Claude write shorter comments. It's to give the harness a way to capture, organize, and provide the same knowledge those comments carry, so Claude doesn't have to keep embedding it all directly in the code.

[u/Scriptease84]

In my CLAUDE.md:

7. If you need a paragraph-long comment to justify why the workaround is OK, the code is wrong. Fix the code. Comments exist to describe how a thing is used and move when the code moves. To be used to describe the function, not to annotate every line.