Comment by CharlieDigital
2 months ago
Comments are the ultimate agent coding hack. If you're not using comments, you're doing agent coding wrong.
Why? Agents may or may not read docs. It may or may not use skills or tools. It will always read comments "in the line of sight" of the task.
You get free long term agent memory with zero infrastructure.
Agents and I apparently have a whole lot in common.
Only being half ironic with this. I generally find that people somehow magically manage to understand how to be materially helpful when the subject is a helpless LLM. Instead of pointing it to a random KB page, they give it context. They then shorten that context. They then interleave context as comments. They provide relevant details. They go out of their way to collect relevant details. Things they somehow don't do for their actual colleagues.
This only gets worse when the LLM captures all that information better than certain human colleagues somehow, rewarding the additional effort.
Right? It's infuriating. Nearly all of the agentic coding best practices are things that we should have just been doing all along, because it turns out humans function better too when given the proper context for their work. The only silver lining is that this is a colossal karmic retribution for the orgs that never gave a shit about this stuff until LLMs.
You are seeing very similar trends in GTM
suddenly everyone cares about data hygiene. But it’s not like this shouldn’t have always been a priority
> It's infuriating. Nearly all of the agentic coding best practices are things that we should have just been doing all along
There's a good reason why we didn't though: because we didn't see any obvious value in it. So it felt like a waste of time. Now it feels like time well spent.
> Only being half ironic with this. I generally find that people somehow magically manage to understand how to be materially helpful when the subject is a helpless LLM. Instead of pointing it to a random KB page, they give it context. They then shorten that context. They then interleave context as comments. They provide relevant details. They go out of their way to collect relevant details. Things they somehow don't do for their actual colleagues.
"Self-descriptive code doesn't need comments!" always gets an eye-roll from me
Helping the AI is helping themselves. You're doing your job, the AI is helping with their job.
This isn't just great advice ⸻ it's terrific advice. I'd love to delve a little deeper.
Would you like me to draft a list of recommendations for how best to use comments?
I didn't even know there was a "three em dash". Bravo.
Huh. It's displayed taking up three cells in my terminal, but laid out as if its width were one cell. Irritating. I wonder if there are any other grapheme clusters that don't properly fit in two cells?
2 replies →
We figured out how to remove that crap in our ICLR 2026 paper: https://arxiv.org/pdf/2510.15061
[dead]
This.
Its also annoying to have to go through this stack
code -> blame -> commit message -> jira ticket -> issue in sales force...
Or the even better "fixes bug NNNNN" where the bug tracking system referenced no longer exists.
Digging through other systems (if they exist) to find the nugget in an artifact is a problem for humans too.
Comments are great for developers. I like having as much design in the repo directly. If not in the code, then in a markdown in the repo.
Meanwhile, some colleagues: "Code should have as little comments as possible, the code should explain itself." (conceptually not wholly wrong, but it can only explain HOW not WHY and even then often insufficiently) all while having barebones/empty README.md files more often than not. Fun times.
Comments are great until they diverge from the code. The "no comments, just self-explanatory code" reaction comes from the trauma of having to read hundreds of lines of comments only to discover they have nothing to do with how the code actually works, because over time the code has received updates but the comments haven't. In that case it's better to just have no comments or documentation of any kind--less cognitive overhead. This is a symptom of broken culture, but the breakage is the same kind that has managers salivating over LLM vibeslop. So I totally get where your colleagues might be coming from. Working within the confines of how things actually are it could be totally reasonable.
12 replies →
Actually good naming does plenty to explain the why. And because it’s part of the code it might actually be updated when it stops being true.
3 replies →
> the code should explain itself.
This is a good goal. You should strive to make the code explain itself. To write code that does not need comments.
You will fail to reach that goal most of the time.
And when you fail to reach that goal, write the dang comments explaining why the code is the way that it is.
4 replies →
Comments are mostly useful when they explain the why, not the what.
HOW vs WHY is a great destination between design and documentation.
Gonna try and use that throughout my life. Thanks!
This is also a great way to ensure the documentation is up to date. It’s easier to fix the comment while you’re in the code just below it than to remember “ah yes I have to update docs/something.md because I modified src/foo/bar.ts”.
People moving docs out of code are absolutely foolish because no one is going to remember to update it consistently but the agent always updates comments in the line of sight consistently.
Agent is not going to know to look for a file to update unless instructed. Now your file is out of sync. Code comments keeping everything line of sight makes it easy and foolproof.
Experience doesn’t leave me with any confidence that the long term memory will be useful for long. Our agentic code bases are a few months old, wait a few years for those comments to get out of date and then see how much it helps.
The great thing about agentic coding is you can define one whose entire role is to read a diff, look in contextual files for comments, and verify whether they’re still accurate.
You don’t have to rely on humans doing it. The agent’s entire existence is built around doing this one mundane task that is annoying but super useful.
Idk if u are serious.
Yes, lets blow another 5-10k a project/month on tokens to keep the comments up to date. The fact ai still cannot consistently refactor without leaving dead code around even after a self review does not give me confidence in comments…
Comments in code are often a code smell. This is an industry standard for a reason and isnt because of staleness. If u are writing a comment, it means the code is bad or there is irreducible complexity. It is about good design. Comments everywhere are almost always a flag.
Note, language conventions are not the same.
> “BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272) in a single session, wasting ~250K API calls/day globally.”
That's revealing waaaay more than the agent needs to know.
Doesn't look like privileged information to me.
Seems to me like everyone's just grasping at straws to nitpick every insignificant little thing.
Hmm, I'm sure if you're getting parent's comment.
I think a big question is whether one wants your agent to know the reason for all the reasons for guidelines you issue or whether you want the agent to just follow the guidelines you issue. Especially, giving an agent the argument for your orders might make the agent think that can question and so not follow those arguments.
> If you're not using comments, you're doing agent coding wrong.
Comments are ultimately so you can understand stuff without having to read all the code. LLMs are great when you force them to read all code, and comments only serve to confuse. I'd say the opposite been true in my experience, if you're not forcing LLMs to not have any comments at all (and it can actually skip those, looking at you Gemini), you're doing agent coding wrong.
You're wasting context doing that when a 3 line comment that the agent itself leaves can prevent the agent from searching and reading 30 files.
You're wasting context re-specifying what the code should already say, defining an implementation once should be enough, otherwise try another model that can correctly handle programming.