6 ms·

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 w

by causal 6mo 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`

pixl97 6mo ago
Project trackers come and go, but code is forever, hopefully?
CharlieDigital 6mo 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.
- perching_aix 6mo ago
  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.
  - dgunay 6mo ago
    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.
    - thunky 6mo ago
      > 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.
    - AbstractH24 6mo ago
      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
  - saghm 6mo ago
    > 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
  - fwipsy 6mo ago
    Helping the AI is helping themselves. You're doing your job, the AI is helping with their job.
- prepend 6mo ago
  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.
  - hk__2 6mo ago
    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”.
    - CharlieDigital 6mo ago
      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.
  - KronisLV 6mo ago
    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.
    - Pxtl 6mo ago
      > 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.
      - bandrami 6mo ago
        But you will also fail to keep the comments and code synchronized, and the comment will at some point no longer describe why the code is doing whatever it does
- causal 6mo ago
  > “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.
  - sfn42 6mo ago
    Doesn't look like privileged information to me. Seems to me like everyone's just grasping at straws to nitpick every insignificant little thing.
- embedding-shape 6mo ago
  > 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.
  - CharlieDigital 6mo ago
    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.
    - embedding-shape 6mo ago
      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.
- joe_the_user 6mo ago
  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.
- zingar 6mo ago
  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.
  - tyre 6mo ago
    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.
    - rustystump 6mo ago
      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.
- noman-land 6mo ago
  This isn't just great advice ⸻ it's terrific advice. I'd love to delve a little deeper.
  - saxelsen 6mo ago
    Would you like me to draft a list of recommendations for how best to use comments?
  - jaxn 6mo ago
    I didn't even know there was a "three em dash". Bravo.
    - zahlman 6mo ago
      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?
      - sheept 6mo ago
        CJK text is typically rendered as 2 columns per character, but in general this is dependent on the terminal emulator
      - voidUpdate 6mo ago
        Yes, lots https://thottingal.in/blog/2026/03/22/complex-scripts-in-terminal/ https://thottingal.in/blog/2026/03/22/complex-scripts-in-ter...
  - km144 6mo ago
    [dead]
  - Der_Einzige 6mo ago
    We figured out how to remove that crap in our ICLR 2026 paper: https://arxiv.org/pdf/2510.15061 https://arxiv.org/pdf/2510.15061
- zer00eyz 6mo ago
  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.
treexs 6mo ago
well yeah since they tell claude code the business decisions and it creates the comments
JambalayaJimbo 6mo ago
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.
semiquaver 6mo ago
Most large private codebases look like this. Anthropic did not expect the source to leak.
yalok 6mo ago
vibe-coded all the way through
wilg 6mo ago
Exactly the type of comment Claude Code would write
saghm 6mo ago
> 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?
- noosphr 6mo ago
  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.
  - saghm 6mo ago
    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?
    - throwup238 6mo ago
      That’s what a source map is. It’s included in debug builds so that browser debuggers (and others) can step through the original code, comments and all, instead of the compiled javascript (which back in the day could become an undecipherable mess of callbacks if you were transpiling async/await to the legacy Promise API). Unfortunately in many bundlers making a mistake like this is as easy as an agent deleting “process.env[‘ENV’] === ‘debug’” which they’ll gladly do if you point them at a production or staging environment and ask them to debug the stripped/compiled/minified code.
      - saghm 6mo ago
        I see. I had read that it was a source map that was leaked here specifically, but my vague understanding of the term was mostly that it might be a way to trace back JavaScript lines to the TypeScript it compiled from, since I don't have much of an understanding of all of the other various steps that are part of a JavaScript build nowadays. I think I still disagree with the parent comment premise that "they probably thought minifying was enough", since it sounds likely they were doing all of those other steps. The issue seems like insufficient auditing of the build process (especially if agents were involved, which seems likely for Anthropic) rather than not doing all of the usual JS build stuff.
WatchDog 6mo ago
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?

by causal 6mo ago

pixl97 6mo ago

Project trackers come and go, but code is forever, hopefully?

CharlieDigital 6mo 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.

perching_aix 6mo ago
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.
- dgunay 6mo ago
  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.
  - thunky 6mo ago
    > 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.
  - AbstractH24 6mo ago
    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
- saghm 6mo ago
  > 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
- fwipsy 6mo ago
  Helping the AI is helping themselves. You're doing your job, the AI is helping with their job.
prepend 6mo ago
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.
- hk__2 6mo ago
  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”.
  - CharlieDigital 6mo ago
    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.
- KronisLV 6mo ago
  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.
  - Pxtl 6mo ago
    > 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.
    - bandrami 6mo ago
      But you will also fail to keep the comments and code synchronized, and the comment will at some point no longer describe why the code is doing whatever it does
causal 6mo ago
> “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.
- sfn42 6mo ago
  Doesn't look like privileged information to me. Seems to me like everyone's just grasping at straws to nitpick every insignificant little thing.
embedding-shape 6mo ago
> 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.
- CharlieDigital 6mo ago
  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.
  - embedding-shape 6mo ago
    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.
joe_the_user 6mo ago
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.
zingar 6mo ago
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.
- tyre 6mo ago
  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.
  - rustystump 6mo ago
    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.
noman-land 6mo ago
This isn't just great advice ⸻ it's terrific advice. I'd love to delve a little deeper.
- saxelsen 6mo ago
  Would you like me to draft a list of recommendations for how best to use comments?
- jaxn 6mo ago
  I didn't even know there was a "three em dash". Bravo.
  - zahlman 6mo ago
    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?
    - sheept 6mo ago
      CJK text is typically rendered as 2 columns per character, but in general this is dependent on the terminal emulator
    - voidUpdate 6mo ago
      Yes, lots https://thottingal.in/blog/2026/03/22/complex-scripts-in-terminal/ https://thottingal.in/blog/2026/03/22/complex-scripts-in-ter...
- km144 6mo ago
  [dead]
- Der_Einzige 6mo ago
  We figured out how to remove that crap in our ICLR 2026 paper: https://arxiv.org/pdf/2510.15061 https://arxiv.org/pdf/2510.15061
zer00eyz 6mo ago
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.

treexs 6mo ago

well yeah since they tell claude code the business decisions and it creates the comments

JambalayaJimbo 6mo ago

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.

semiquaver 6mo ago

Most large private codebases look like this. Anthropic did not expect the source to leak.

yalok 6mo ago

vibe-coded all the way through

wilg 6mo ago

Exactly the type of comment Claude Code would write

saghm 6mo ago

> 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?

noosphr 6mo ago
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.
- saghm 6mo ago
  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?
  - throwup238 6mo ago
    That’s what a source map is. It’s included in debug builds so that browser debuggers (and others) can step through the original code, comments and all, instead of the compiled javascript (which back in the day could become an undecipherable mess of callbacks if you were transpiling async/await to the legacy Promise API). Unfortunately in many bundlers making a mistake like this is as easy as an agent deleting “process.env[‘ENV’] === ‘debug’” which they’ll gladly do if you point them at a production or staging environment and ask them to debug the stripped/compiled/minified code.
    - saghm 6mo ago
      I see. I had read that it was a source map that was leaked here specifically, but my vague understanding of the term was mostly that it might be a way to trace back JavaScript lines to the TypeScript it compiled from, since I don't have much of an understanding of all of the other various steps that are part of a JavaScript build nowadays. I think I still disagree with the parent comment premise that "they probably thought minifying was enough", since it sounds likely they were doing all of those other steps. The issue seems like insufficient auditing of the build process (especially if agents were involved, which seems likely for Anthropic) rather than not doing all of the usual JS build stuff.

WatchDog 6mo ago

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?