Comment by causal
2 months ago
I'm amazed at how much of what my past employers would call trade secrets are just being shipped in the source. Including comments that just plainly state the whole business backstory of certain decisions. It's like they discarded all release harnesses and project tracking and just YOLO'd everything into the codebase itself.
Edit: Everyone is responding "comments are good" and I can't tell if any of you actually read TFA or not
> “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.”
This is just revealing operational details the agent doesn't need to know to set `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3`
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.
2 replies →
> 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.
3 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.
24 replies →
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”.
1 reply →
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.
1 reply →
> “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.
1 reply →
Most large private codebases look like this. Anthropic did not expect the source to leak.
It's a good comment, it explains the reason for the setting.
They didn't expect to leak their source code.
It's hardly a trade secret, what value is this to a competitor?
I guess they weren't expecting a leak of the source code? It's very handy to have as much as possible available in the codebase itself.
Project trackers come and go, but code is forever, hopefully?
> just YOLO'd everything into the codebase itself
I suspect that's the logical endpoint of trying to provide everything as context to an agent. Why use a separate markdown file and have to waste extra tokens explaining what part of the codebase something applies to when you can just put it right there in the code itself?
The issues is that you should have a work flow that strips the comments before sending the code to production. I'm sure they assumed that minifying it is enough though.
They also weren't supposed to be leaking the code itself either. I don't know enough about JS tooling, but is it possible that this might just be the pre-stripped version?
2 replies →
Exactly the type of comment Claude Code would write
well yeah since they tell claude code the business decisions and it creates the comments
vibe-coded all the way through