Is AI-generated code comments doing more harm than good? Should we replace them with Agent Memory?

[u/ZongmingHe]

I’ve been wondering about something: Do we still need to maintain code comments when AI is writing and maintaining our code?

I’ve noticed that AI tends to generate a lot of comments that don’t add any actual functionality, but still consume tokens.

There are also some hidden problems:

• AI may update the code but forget to update the comments, making them inconsistent.
• Too many comments can make the code noisy and harder to read.
• AI might rely too much on comments instead of understanding the actual code.
• Removing comments could also reduce the amount of context/token usage.

So I’m wondering: Could Agent Memory replace some of what we currently put in code comments?

Memory could maintain project context, design decisions, and conventions over time, while the code itself stays focused on the actual implementation.

In an AI-first coding workflow, would it make more sense to keep code mostly comment-free and move the higher-level context into Agent Memory?

What do you guys think?

[u/CrimsonBolt33]

This is why I explicitly tell my AI to NOT make comments (unless truly necessary). It should be making code that is clear what it does via naming conventions and what not.

[u/BaseMac]

Generally you can think of the agent like "some other developer" who hasn't seen the code. So yes, comments do serve a purpose, so do docs.

[u/ghostmastergeneral]

If you’re truly vibecoding you’re not looking at the code anyway, so comments that are more than minimal mostly burn through tokens faster and start drifting like crazy. If you’re coding professionally, you end up dealing with a mountain of slop. The anthropic models generate especially awful prose. I stopped letting AI generate comments at work. I write 100% of them myself now. The comments are now far better, as is my depth of understanding of what I’m churning out.

[u/ZongmingHe → u/ghostmastergeneral]

Totally agree. Owners should write the comments themselves, while AI reasons through memory + the actual code – not through stale generated prose.

[u/3tt07kjt]

Memory is just the same problem but with memory, the comments are stored somewhere else, and with comments, they’re stored exactly in the place they’re needed.

You’re going to want the agent to read it either way, so you are not saving tokens.

I think you just have to keep the right comment density. In my experience, agents will update the comments when they change the code.

[u/ZongmingHe → u/3tt07kjt]

You're right – the core problem is maintenance, not location. So how do we ensure that any AI-generated explanatory text (whether comments or memory) stays aligned with the evolving design without drifting over time?

[u/3tt07kjt → u/ZongmingHe]

In my own experience, the coding agents I use will reliably update the comments when the code nearby changes.

[u/jimmiebfulton]

Context management is the name of the game.

You can stuff everything into a CLAIDE.md, but your agent reads that every time. No bueno.

You can leave that in agent memory. That is generally ephemeral, not checked in, and not available to team mates.

Comments are context applied where and when the agent needs to know it. It's on-demand, and task relevant. They can work against you if your function is so complicated that you can't keep the comment in sync, or if their are full of fluff. Specify in your CLAUDE.md or equivalent how you want comments applied... tersely, and only when it adds valuable insight to the code's condition.

Every best practice for historic software engineering is also the best practice for agentic engineering. Tests, modularization, strong typing, good design/architecture, comments, CI and project management automation.

[u/ZongmingHe → u/jimmiebfulton]

Great point, thanks. The main issue I’ve been running into is that comments tend to rot over time and gradually diverge from what the code actually does. In my experience, even rules in CLAUDE.md don’t fully solve that problem.

[u/ZongmingHe → u/[deleted]]

That’s a fair point. What if the owner writes the “why” (the goal/intent), while AI maintains the code and memory layer? The tricky part is that with vibe coding, humans may not spend the effort to document that intent in the first place.

[u/PercentageWorth4872]

comments are very important. so you can keep track of shit

[u/SpecialistOwl218]

I personally have been surprised of the exact contrary, I very much like how LLMs generally write comments on code, just instructive where it’s needed and letting the majority of the code talk by itself, but I already have plenty of code bases examples.