Summarizer

It’s also pretty damn obvious when LLMs write code. Nobody out here commenting every method in perfect punctuation and grammar.

It's a pretty sad state of affairs when someone can say with a straight face "Nobody out here" (sic) taking their job seriously and giving it the care and attention it rightly deserves.

I have been doing this for years, especially for libraries (internal or otherwise), anything that's `pub`/`export`, or gnarly logic that makes the intent not obvious. Not _everything_ is documented, but most things are. I'm doing it because I know how much I appreciate well-written documentation. Also this is a bit niche, but if you're using Rust and add examples to doc-comments, they get run as tests too. Also given we both managed to produce more than one sentence, and include capital letters in our comments, it's entirely possible both of us will be accused of being an AI. Because, you know... People don't write like this, right?

I feel seen...

Commenting every method, how pedestrian! I comment every letter of my code!

if you've changed a function and are worried about the reason for the change not being tracked or disappearing, then add it as a comment, the commit message is not the place for this.

I do this too. I’ll have a design.md and roadmap.md checked into the repository.

Honestly the aggressive verbosity of github copilot is half the reason don't use its suggested comments. AI generated code comments follow an inverted-wadsworth-constant: Only the first 30% is useful.

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.

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

Would you like me to draft a list of recommendations for how best to use comments?

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.

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.

How would you use good naming to explain this https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overv... Or how would you name methods and variables to explain why some payment reconciliation process skips matching for transactions under 0.50 EUR and just auto-approves them, because the external payment processor rounds differently than the internal ledger at sub-euro amounts, creating mismatches that were flooding the finance team's exception queue in 2013, explained more under Jira issue ZXSV-12456 and more details are known by [email protected] . The threshold was chosen after analyzing six months of false positives, when it's any higher someone being undercharged doesn't get caught. I don't think autoApproveThreshold = 0.50 or anything like that would get the full context across, even if the rules themselves are all code. I think surely you can have both! Code should explain itself as often as possible, but when you hit a wall due to some counter-intuitive workarounds being needed, or some business rules or external considerations that you need to keep track of, then comments also make sense. Better than just putting everything in a Jira issue somewhere, given that it often won't be read by you or others and almost certainly will not be read by any AI agents (unless you have an MCP or something, but probably uncommon), or spending hours trying to get the code to explain something it will never explain well. I've had people ask me about things that are covered in the README.md instead of reading it.

You’ve correctly identified that naming isn’t sufficient for all communication. Name the things that stay constant in the code and explain the things that vary with a particular implementation in version control messages. Version control as a medium communicates what context the message was written for, which is far more appropriate than comments.

> Name the things that stay constant in the code and explain the things that vary with a particular implementation in version control messages. Then the question becomes how often we look in the version control history for the files that we want to touch. Which of these is more likely: A) someone digging into the full history of autoApproveThreshold and finding out that they need to contact [email protected] or reference ZXSV-12456 B) or them just messing the implementation with changes due to not reviewing the history of every file they touch If someone is doing a refactor of 20 files, they probably won't review the histories of all of those, especially if the implementation is spread around a bunch of years, doubly so if there are a bunch of "fixes" commit messages in the middle, merge commits and so on. I've seen people missing out on details that are in the commit log many, many times, to the point where I pretty much always reach for comments. Same goes for various AI tools and agents. Furthermore, if you want to publish a bit of code somewhere (e.g. Teams/Slack channel, or a blog), you'd need to go out of your way to pull in the relevant history as well and then awkwardly copy it in as well, since you won't always be giving other people a Git repo to play around with. It's not that I don't see your point, it's just that from where I stand with those assumptions a lot of people are using version control as a tool wrong and this approach neither works now, nor will work well for them in the future. It's more or less the same issue as with docs in some Wiki site or even a separate Markdown file (which is better than nothing, definitely closer than a Wiki, especially if the audience is someone who wants an overview of a particular part of the codebase, or some instructions for processes that don't just concern a few files; but it's still far removed from where any actual code changes would be made, also a downside of ADRs sometimes).

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!

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

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

But copilot code review agent is pretty good at catching when code and comments diverge (even in unrelated documentation files).

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.

This is honestly such a bad argument against comments. I'm gonna note down my reasons for doing things and other information I deem useful, and if some other dipshit 5 years from now when I've moved on comes along and starts changing everything up without keeping the comments up to date that's their problem not mine. There was never anything wrong with my comments, the only thing that's wrong is the dipshit messing things up. Doesn't matter what I do, the dipshit is going to mess everything up anyway. Those outdated comments will be the least of their worries.

You may be a bit overconfident about how clear you will be with your comments. The “dipshit” doesn’t mess everything up for fun. They don’t understand the comments written by the previous “dipshit” and thus are unable to update the comments.

Oh really? I'm overconfident in my ability to write and read simple clear text notes? Here's what I think. I think you guys heard the "self-documenting code" BS and ate it up, and now you're grasping at straws to defend your cargo cult position, inventing these "problems" to justify it. If you're looking at some code and there's a comment saying something that doesn't make sense to you, maybe that's a clue that you're missing a puzzle piece and should take a step back maybe talk to some people to make sure you're not messing things up? Maybe, for a non-dipshit, that comment they don't understand could actually be helpful if they put some effort into it? Also just to be clear I don't think this is a likely occurrence unless someone doesn't know squat about the codebase at all - my comments generally assume very little knowledge. That's their whole purpose - to inform someone (possibly me) coming there without the necessary background knowledge. It just isn't feasible to include the why of everything in the code itself. And it sure as hell is better to include some info as comments than none at all. Otherwise a bug will often be indistinguishable from a feature. And I don't think dipshits mess things up for fun. I think they just suck. They're lazy and stupid, as most developers are. If I'm there I can use reviews etc to help them suck less, if I'm not they're free to wreck my codebase with reckless abandon and nothing I do will make any difference. I cannot safeguard my codebase against that so there's no point in trying and the fact that this is your argument should make you stop and reconsider your position because it's far fetched as fuck.

And then you find out the dipshit that didn't keep the comments up to date was you all along

It wasn't.

> that's their problem not mine IME unfortunately that's not actually the case. It very much is your problem, as the architect of the original system, unless you can get yourself transferred to a department far, far away. I've never managed that except by leaving the company. To be clear, I don't believe it should be this way, but sadly unless you work in an uncommonly well run company it usually is.

I really can't imagine this ever becoming a real problem. Not once have I ever worked in a place where any kind of leadership would ever give a shit about comments nor anything else in the code itself. The lowest level leadership has ever gone is click a button to see if it works. And if anyone has a problem with comments existing it's trivial to find/replace them out of existence. Literally a one minute job, if you actually think the codebase would be better without them. This is such a humongous non-issue it's crazy man.

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.

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.

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

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.

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.

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

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

Exactly the type of comment Claude Code would write

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