My coworkers continue to dump hundreds of lines of AI documentation in every PR and every other line of code has between one and ten lines of AI generated comments, talking about the real unlock and how things are byte for byte identical on the load bearing path or how the acceptance ladder is misleading.
Features are coming out and metrics are improving, but we’re basically in a post readability code base, with the occasional performative comment about a variable name.
I don’t really know how to address this situation or if it needs addressed. I certainly don’t read the long-winded AI comments or the AI documentation, but perhaps it’s useful for the AI on its next pass.
My "favorite" Claudism is when I critique its work and ask it to remove some unnecessary part of the design -- and then the diff has more green than red because it added comments about why the code is no longer there -- the code that was never in the mainline and never asked for!
Oh god this has been driving me nuts since Opus 5 landed. Every docblock is filled with long-winded jargon explaining why this design is superior to some other design, which never existed as far as any dev who might read that comment is concerned.
This has been a thing for long while, on codex too.
You ask it to do something, then tell it to do something in a different way, then it assumes it needs to do the refactor in a backward compatible way, or creates migrations for it etc.
This is why I started adding a PROJECT.md file to all my projects and a hook for claude to read it.
It contains (Among other things) stuff like "this is a single user personal project, I'm the only user, this will never be open to the public internet" etc.
It kinda-sorta tones down the proclivity to worry about backwards compatibility and slight edge cases where if someone has edited some template and the new code doesn't support it.
Oh good I thought I was doing something wrong! Using ChatGPT web for planning, ask for a prompt then notice something weird in the prompt and whether I:
1) use the edit in-place functionality; or
2) ask it to rewrite to remove something
It'll write the prompt as if the agent (codex) knew about the conversation and add "don't do X" etc. At first that bothered but I realized it doesn't really change the output so I stopped caring.
I remember when I was updating some formats for my apps data files and it ended up writing v2 and laying it on top of the old one. Ended up just telling it to delete the entire feature and start again. I do think claude.md instructions help though.
I hate that I have to change the way I write to avoid AI-isms. I loved using "load bearing" to describe weird code that you think you can delete but is actually holding everything together.
Now people think I'm just parroting what Claude said. It sucks. I want my catch phrases back, I guess this is how em dash users felt
I used to use em-dashes for explanatory clauses--like this one, for example--when using commas would make the sentence difficult to parse due to other nearby commas.
They're only a LinkedIn-ism when used to create an unduly dramatic juxtaposition for an otherwise mundane idea. But now they set off people's AI radar when used for any reason at all.
Perhaps I am biased because I find the use of em-dashes without spaces (as is common in English typesetting) to be inherently ugly so I'm not too unhappy to see their use discouraged.
Good instinct. Fair challenge. This corrects my framing. It makes your point sharp. This is a significant finding. Positively confirmed. That settles it, and it flips the picture. Honest verdict - this is not small. Let me wire it in.
just add to markdown instructions to check that this failure mode isn't happening in its diff before yielding back to human review. Any issue that occurs more than once, you can just put in the review markdown instructions so you don't need to look at it twice.
It's not just claude, all AI is unable to produce something concise. On the surface everything looks 'good' whether code or prose, but then if you dig a bit, try and understand the whole text you quickly realise that 80% of it is unecessary and the whole thing could have been re-worded/re-coded into something a fraction of its size and complexity.
I asked Sol to reduce the length of some documentation we had by making it more concise. It came back after 20 minutes of work, did a line count and was aghast that the line count had somehow increased...
It's not that it fundamentally isn't able to produce something concise, it's that the business model of the companies developing these models rests on selling tokens...
because human writing IS not just producing the Next token, sometimes you write shit and then go back and find ways to improve and try to play tricks inside the structures only you or your coauthors understand. AI doesnt do this
Exactly! That's also why almost every slop commit I see has a linecount like +700 / -20, whereas human commits often end up net zero. I try to remove more lines than I add, if possible, but LLMs will just add more bloat, forever.
I don’t know. The old models were much more concise, answering your question in a couple of sentences. At some point they just started outputting walls of text for every prompt.
Bullshit. It would cost them more money to post process all the bullshit and then ship that, instead they just point the cannon at your face and pull the trigger.
I had Claude knock out a feature but it was too big of a change set for a single PR so i set up a worktree and started extracting parts piecemeal. Along the way I would clean up and rewrite pieces. By the end of this process i had abandoned everything Claude wrote and looking back at the original branch I was like "oh my god, that's so bad in so many ways, i can't believe i was actually just gonna ship that"
I have to ask Claude to compact the comments every time, and I give specific criteria for it. Never ever reiterate what’s in the code, never mention decisions not made, never mention the conversation, etc etc.
Even then it is conservative. For the love of God, compact the comments.
Comments become a huge maintenance burden, especially in the age of AI. They just grow and grow, and then mislead the AI later on.
I just wrote a utility to rip all comments out of the code. Now the code is fully uncommented and it has saved lots of input tokens and also lots of meandering because the model is no longer getting stuck on bad ideas it told itself about.
I set a line budget for comments (also wiki page parts, chat responses, etc). That only helps when I ask it to do a second pass to reword everything to the budget and add links. I think they tuned it this way to stash reasoning dumps in the code. Unlike human developers, it has no context in its head, other than general GitHub knowledge.
I’ve a codebase filled with references to §x.y section of documentation that Claude itself prepares and never updates; which is exactly what many devs would do, I guess, joke’s on us.
Yeah this is awful. Every codebase becomes a graveyard of references to ideas or behaviors that were barely considered. It's probably also a compounding source of context poisoning when a minority of the comments/documentation are about how the current code actually works.
It also likes to spew references to documents that are not, and never have been, in the repo. So if you're not careful you'l have comments all over your codebase saying things like: foo() - Perform foo action as documented in PRIVATE_INTERNAL.doc
I found this as well, but I found it usually refers to a scratch file it made and purposely did not commit (either by my decision or its). Not that this makes it better, but at least it makes the AI world make a bit more sense to me
This is a common problem, and I don't get why LLMs have not been tuned to stop this nonsense. It is writing comments as if the audience is you, the user in the session, while obviously code comments are meant for future readers.
When I'm writing technical documentation, it keeps the explanations in. Same when writing non-technical documentation. When I was having it attempt to generate a Pathfinder 1e class for a Sword Dancer, it was leaving in notes about why it removes things I told it to remove/rework.
And it isn't just Claude. I've seen the same with GPT models, with Grok, with Deepseek. Each AI isn't quite the same with how it approaches this, but in every case they seem to have a strong bias to retaining information, even bad information that we want gone, so it is like they have a, dare I say, subconscious bias to retain the information. Putting a note in a comment or explaining why to not do something or something was undone is a good way to retain information while still achieving the goal (well, if you ignore the part about the human intention for the information to be gone).
This then weakens the AI in the future, as I find AI struggles with the more incorrect information. Sure, a comment saying "not X because Y" is less 'context damage' than a comment saying "X" (assuming X is wrong), but it is still a slight shift to X being present in context in some way. One off, AI's seem to perfectly handle this without issue. But after hundreds or thousands of cases build up? The attention mechanism seems unable to keep up and incorrect information flows it. This effectively creates a sort of vibe coding maximum size unless there is a human janitor cleaning up the bad information on the context stays nice and clean.
But this is all simply a feeling I get as I use AI to do different things and isn't at all backed up by any formal study.
Have you considered talking about it? You're in a professional environment collectively working in a new way with a group of people. It's up to somebody to have opinions about what does and doesn't suck. If you silently go along and don't say anything you're dooming yourself and all of us to a lifetime of this garbage.
It's not the ocean, it's the poster's own team. A simple "AI comments suck" in a sprint retro would be trivially easy and would at least start the conversation.
While I agree with the spirit of what you're saying, it is very similar to whenever anyone complains about things where they work. "Well, why don't you just raise it with management?" You're assuming that management
1) Understands the problem ("what are comments?")
2) Accepts that it is a problem ("how can more comments be a bad thing?")
3) Cares enough to solve the problem ("is this issue really a priority to solve right now? just accept the PR and we'll go back and fix if needed some other time cough never cough")
4) Believes you (this can take many forms, but the most common is, subconsciously, "this other engineer says it's not a problem, so I'll just assume it's not since that's easier")
All of these logistical, political and social factors are "the ocean"
Sprint retro is with your own team. And disagreement isn't a problem, at least then there would be the potential to come to a common understanding between the GP comment and their coworkers.
I usually require to file an issue in bug tracker about problem in #3 and then follow all its updates to prevent silent closing by management. It won't help but annoys management a lot and they afraid to get more backlog issues of such sort from me in the future.
Doesn't matter. You'll come off as the baddie. It's the foreseeable future. Best just to learn how to interpret AI generated shit, or learn how to run it through AI and have it translate it to a more concise format without all the buzzwords. It'll take getting used to, but it'll save your career.
You don't have to come across as the baddie. There are plenty of neutral ways to start the conversation. E.g., "I notice that there's a lot more generated comments lately. How much are people finding those useful?"
If you really want to save your career, learning how to have real conversations is a vital skill.
Have you worked in corporate recently or at a particularly toxic one?
Asking because when I was at capital one, certain comments or questions about topics like this, would actually get you noticed negatively by your manager and being disruptive to what leadership wants hurts your career.
In fact being the one to ask and point out questions like yours ultimately got me PIP'ed and removed from the company. So, like, yeah, being vulnerable and the first one to tell the truth is risky. That's why the bystander effect can happen and in politics or risky situations silence is a common response, and why we don't have more courageous people doing the right thing - because the risk is higher on the person speaking up and the rewards aren't disproportionately in their favor (but are evenly distributed though, so its not favorable for you as I learned from a game theory perspective to voice up / defend certain stances).
Capital One is a particularly toxic work environment, and I'm not sure that your experiences there apply to other companies.
I started my first post-Capital One job a few months ago, and I'm still not used to the fact that this company expects everybody working here to still be working here in two years. Most employers are not going through everybody with a fine tooth comb every 6 months hunting for any hint of an excuse to PIP them.
The founder CEO (with a cult of personality) really believes that it is the way to "top tech talent." He comes from a management consulting background and tries to manage the software organization like they're consultants. Leads to a very bottom heavy organization, with a lot of juniors, many of whom get PIPed right as they're starting to become useful. It leads to high turnover with a lot of backstabbing, and very short term thinking because everybody is always focused on the next performance management cycle.
It was really a bizarre place to work, because work-life balance was amazing, the benefits and vacation were great, but twice a year there was this insane hunger games.
They really chilled out the performance management process from 2020 or so through 2023, so people who worked there then didn't always notice.
Ah yeah that explains my experience a bit better. I was there in the COVID wfh time, 2020 or so, then rejoined 2024 when I experienced things not too unlike what you described. (except I joined as a principal, ~8-10 years of experience, and received backstabbing and lies from juniors and managers (edit and tech lead)).
I don't recommend going to Plano, TX and joining the Auto Navigator product division.
I grant that sane behaviors may not always be successful at toxic companies. That seems true by definition. But I don't think general career advice should be based on what is (temporarily) safe at the bottom decile.
Also, if you go back you'll note that I didn't suggest that people "tell the truth". I suggested people ask a neutral question about an obvious phenomenon. If it's unsafe to give an honest answer, most people won't, so it'll be a short discussion. But if it's a topic with some room, it can be the start of a good conversation and possibly a useful change.
Ah, I see. I didn't specifically think Capital one was toxic, though, more recently after sharing about my experience more I've been realizing it may have been.
I can see how that technique works great at a non-toxic company. Thank you.
This reply is not directed to you specifically, but that attitude is why improvement doesn't happen.
"My peers are all bad", "Management has no idea what's going on", "My boss is out of touch", "My staff keep screwing up".
But if you're consistently seeing the problems while everyone else becomes defensive, you (that think that way) need to learn how to communicate effectively in a way that doesn't result in being 'the baddie' and solve the interpersonal dynamic along with the technical problems. "Crucial Conversations" is a good place to start.
When AI directives are coming from the top down - when everyone above you all the way up to the CEO is all in on AI - the writing is on the proverbial wall. I'm not saying it will be that way forever, but it is the foreseeable future, and those that don't jump on the train will be left behind. It's just life.
What is this defeatist attitude? I don't know where you work, but it is not my impression that AI has instantly turned all developers into mindless AI-pilled sheep. If you feel like a simple suggestion like that will cost you your career, then it doesn't sound like a place where any constructive criticism would have been accepted even before AI.
There is no single conforming "corporate world" that applies to all companies. If AI is treated religion in your company that sounds like a local problem, even if it seems like a trend.
Besides, GP was not talking about corporate, but about the inability to even suggest an improved usage of LLMs among their developer peers, as if every line of code generated by AI is now gospel and questioning it is treated as heresy. This level of defeatism is beyond cynical and approaching childish.
There's a reason 3rd places exists. There's a social construct that off-work discussion (even when on-work) stays off work.
If your coworker is professional and cares about keeping channels open, they too will respect the unspoken rules that govern 3rd place neutral locations.
Blame it on the alcohol later on if it actually pisses someone off.
This is the third place. There is no real 3rd place in real companies usually. Not in mine, when i work remotely for company from other side of continent.
I think the biggest issue might not be the immediate team but upper leadership. Companies which have mandated AI usage override a lot of what an individual or individual team wants. If that’s the case then it would be a lot like fighting the ocean, especially if your immediate team sees having AI write docs as an easy way to move the needle on LT’s AI monitoring dashboard.
> My coworkers continue to dump hundreds of lines of AI documentation in every PR and every other line of code has between one and ten lines of AI generated comments
That's the behavior being discussed. In my experience, overly large PRs are a detriment to productivity, so if anything my suggestion (asking one's coworkers to stop that) might lead to an improvement in velocity. If I have to read an essay before and throughout every PR, I'm not going to be able to review that very quickly.
It's the management desired direction, if the place is anything like my workplace. Everyone is all in on AI, and if you're not using it for everything possible, you're on the chopping block.
And, really, it works. You can copy and paste between tickets and Claude, and then do manual testing. Then you tell Claude to self-review for clarity and minimalism, and stop worrying. Sure, today it's not as good as a human, but for almost all the code out there, it gets the job done. There's no skill needed any more, and if the boss doesn't care about quality, I don't see why I should.
Your boss can get Claude to make unreadable, noisy, confusing code just as well as you can.
There may not be a career left in software development with these monstrosities, but if there is, it's in using decades of experience to get the abominations to produce something other than unreadable dreck.
If the code itself truly doesn't matter any more, programmers will no longer be paid.
Oh, yeah, the amount of skill needed for programming is quite low these days, the people paying just haven't figured it out quite yet. There's still some needed, but it's closer to line cook than nuclear physicist.
But the managers won't do it, because you still need manual testing to make sure that the AI models got things right. Managers will want to hire someone to do the manual testing.
The amount of skill required is still pretty high, IMO - if we set a requirement that a programmer thoroughly understand what they're shipping.
If we remove that requirement (as most around me seem to be doing), then yeah, not much skill required, but the system is going to steadily trend towards being a buggy, unmaintainable pile of sloppypasta.
Maybe the models get good enough they can handle maintaining that, but anecdotal reports so far seem to indicate we aren't there yet.
Everybody generally agrees on what is garbage. Lot of senior management doesn't think AI is garbage or even if they privately think so, they don't say that openly. Falling in line, peer pressure, not wanting to come across as anti-AI luddite etc. All those issues affect the individual contributors too + the added challenge of perception in front of those who decide the bonus and lately, continued employment.
In this fucked up job market, it is easier said than done.
I feel like the chain kinda goes all the way to the top, to the level of shareholders. My boss needs to give his boss the perception that the engineering team is firing on all cylinders and has high velocity, so that he can sell that story to shareholders who could easily invest in another "AI-native" company and make more money because they're growing like crazy.
I feel like it's all just perception and how companies can sell their stories to investors or potential acquirers, and everything else can be punted and dealt with later when we get acquired or when share prices are a zillion dollars etc.
Yes, talking about it repeatedly has been my process. Individual PRs have been changed but the 4 the next day look the same. The typical response is that they did change the (massive and wordy) PR overview from what AI said, even if it was obviously a minimal change at best. I can’t really argue against lying and going through and picking out every LLMism is not so productive in my opinion.
I don’t have time to go through and flag everything or even read the thousands of lines of code changes that are happening.
You might be presuming a culture that protects free expression. Free expression is hard to protect. Sure, you could express your experience, but it could threaten or offend someone "with power" and they use their "power" to punish you and suppress the ideas you're trying to express.
No, if he speaks against it he gets labeled "anti-AI" and laid off or not promoted. If he stays silent he retains his job.
Corporate Capitalism's main innovation was virtualizing feudalism. Now anyone with a bit of cash flow can be a feudal lord with peasants to do his will. No need to maintain land or fight over it with other feudal lords. There's still fighting, naturally, but now the game isn't zero sum.
The serfs don't get any real say in this model. At best you can bend the lord's ear if you're sufficiently trusted an advisor. But part of the reason you're trusted is to be trusted not to treat the lord like he's too much of an idiot.
A huge problem is that capitalism rewards cash flows and accumulated capital so powerfully that lots of other things just don't matter, potentially for a very long time. Look at GitHub. This leads to immensely extended fuck around phases and "find out" looks like IBM (fossilization and bizarre holdings corporation / dead company parking lot) just as often as it looks like Enron.
I am a programmer but also in management, and if I knew my team thought like that I would be horrified. We absolutely care about what the team members want , like, hate etc. I for once would love someone to bring up stuff like this to me. As long as they are as open minded about things as they would like me to be, there is no issue. But it’s a serious issue to pretend everything is fine while thinking like you say.
Correct. I do believe my _manager_ wants me to have a say etc. but I also know my manager has terrifically little power overall. "In management" just means you can't unionize and have to dance to the company tune.
That's the existential threat right now, isn't it? So much of our industry is top-down being told "agentic programming is the only way forward" and anyone who disagrees is laid off. (I'm in that boat. I've been out of work since April.)
It doesn't feel sustainable now. It won't feel sustainable in the future when companies are trying to operate on an entire fossil layer of LLM-generated legacy code.
Do I expect managers to get smarter about LLMs and their limits or do I "retire" and find an entire new industry to work in?
It's really depressing and there has been a lot of grieving since April that it feels like my entire 20+ year career path disappeared overnight, replaced by something unsustainable and ultimately terrifying.
I was nodding to your post for a short period, then you just had to throw in the usual anti-capitalism zeitgeist rant.
Reframe your context, pretend you're in a communist society, and you could be making the exact same point about speaking up against the grain being bad for you. It feels as though people are brainwashed by anti-capitalism sentiment at the moment, unable to see outside of that context.
That's not the point of my response. It is tiresome, and detracts from meaningful discourse to have the same tired anti-capitalism meme tacked onto everything. It didn't even make sense in the post I was responding to - which is entirely my point.
It's relevant because the feedback mechanism for countering all of this is "theoretically, the firm gets outcompeted by other actors who are not doing the bad things."
I'm pointing out that, due to how strongly capitalism rewards cash flow and previously accumulated capital, that feedback/correcting mechanism is often _extremely slow_.
I've tried doing this, politely pushing back on problems happening from AI use, and it led to a not-so-subtle implication from my manager that I need to STFU or I'll be out of here (Cisco).
My team uses a Claude Code hook that blocks any comment more than 2 lines long, and when tripped it encourages the agent to rewrite the comment more concisely and focus only on the "why" not the "what" of the code. I've found this extremely useful for code reviews.
I was using that approach with Fable to great effect, but with Opus it's useless. It just writes unreadable horseshit anyway, so banning comments entirely results in far more readable code.
Still I always find it funny when I give it code to review that it itself wrote and it immediately says how good the comments are, it's like that obama giving medal to obama meme.
I will say I'm doing some coding right now with Opus 4.8 and I'm shocked by how much commenting it does. I'm going to have to update my docs to tell it to limit it. In my last project w/ Kimi and Deepseek I didn't have this problem, code was decent but not as good as Opus 4.8 - but man the comments were a lot less verbose.
And the tests. Oh god the tests. Personal recent favorite: I asked for some changes to a Dockerfile, which it did ably, and then promptly tested by writing a pytest module that traversed up to the root, read the Dockerfile, and checked that the added lines were present.
Code-generating robots are pretty bad at property-based testing, in my experience. They can do it but they still need a lot of hand-holding. They often regress to writing a mirror implementation as the oracle and trying to enumerate a fixed set of examples they find meaningful.
I'm generally happy with the tests I ask it for, some of which are PBT. It's just the insistence upon memorializing every single change with a test. Maybe encouraging / forcing PBT will dissuade it?
I regret this but at some point I stopped reading generated tests. It feels pointless when our test files are already tens of thousands of lines of — at best — tautological slip which says that the codes does what it does.
I think reading and writing test code is harder than the underlying code itself. You must know both the desired behavior of the code-under-test and whether the test correctly stresses that behavior. And then if you're working on anything more complicated than a single unit test you must also make sure that it doesn't blow up anything adjacent to it (preserve state).
I think enforcing black box testing is the best way to get useful tests out of both humans and robots. They must not know the internals, or it will lead them to do bad things.
Silly AI, doesn't it know that you have to write the test first, see it fail, and only then can you justify making a change to the Dockerfile.
I do wonder if the idea of TDD has influenced AIs to be too prone to testing even when a human would never consider it. I've seen some really silly tests, especially when it starts writing tests for things that are setup to only allow testing. Normally a comment later and it agrees it was pointless, but unless you have something in context to force it, it simply defaults to "test all the things".
Two very useful directives to give AI when it comes to documentation:
1) Document what's there, not the diff. Documentation of how code was removed or changed to fix a bug or add a feature is not useful and difficult to maintain; documentation should explain how code works now.
2) Documentation should live close to the source as possible. Prefer line based comments and standardized function documentation. Top-level sweeping architectural essays are not maintainable for every change.
The last will depend on your codebase. It CAN be very useful to have a human-readable spec documented for the entire program and have it updated when anything changes. But the key is again, you're CHANGING it every time. If you add a whole new disconnected documentation file it should set off alarm bells; nothing in one system is truly disconnected.
We recently added a similar thing to our style guide, It’s astonishing to me that we have to spell this out, that something as obvious as this needs to be explained to LLM’s at all. They’re supposed to be exceeding human intelligence, at least at things like programming, but can’t understand basic things like what code comments are.
> It’s astonishing to me that we have to spell this out, that something as obvious as this needs to be explained to LLM’s at all.
Hehe. Yeah, that tendency of LLMs to document "the story" of the code instead of its current purpose (or non-obvious implementation details) is a pet peeve of mine too. I've added a slew of guidelines to try to sway Claude to not do this, but it still does it often.
At the same time, it feels like something to be expected to have this "failure mode". The model has its context to work on, and what is on its context if not the conversation you've been having (and its internal monologue) and the files it has read? It makes sense that it references the story on its text generations, because that behavior is usually a good thing for an LLM to do. Otherwise, what would it generate? If it generated things that had nothing to do with the conversation in its context, in many cases those things would be seen as "hallucinations", and they'd tend to be RLHF'ed out. So the models that we end up having are the ones that have been reinforced to be most "contextually relevant" and less "hallucinatory".
I might be completely wrong on that of course. It's just my intuitive reasoning of why this seems to be such a prevalent behavior.
RLHF has the same problem as human reviews of AI code: AI code (and comments) look plausible at first, and if you have 100 other PR's to get to, it looks "good enough" and you approve it. I'm sure the humans doing the "human feedback" part of RLHF at anthropic are just as tired as I am at reading all of it, and start to just approve it when it looks plausible.
It's doubly insidious because it trips up the human brain too: When I'm reading a PR saying "fix lock ordering to avoid deadlocks on user deletion", and there's a comment somewhere in the diff saying "// use the fixed lock ordering here", my brain tends to completely forget the fact that the comment doesn't make any sense in its surrounding context. Because it makes perfect sense in the context of being the human reviewing the diff. But it's a slight bit of mental effort to remind yourself "what is this comment going to look like to someone reading the code after this is merged?"
I wouldn't be surprised whatsoever if the RLHF supervisors forget to apply that extra bit of mental effort and say "yup, this comment looks great", forgetting to check the surrounding code to see if it makes sense on its own.
My theory (which might be completely wrong) is that models do this because it improves quality for vibe coders.
When vibe coding the content of user prompts is ground truth and the only way any human thought affect the code base. So if the vibe coder says "do X not Y", recording int comments that "we shouldn't do Y" is important. It ensures that the agent doesn't accidentally decide to do Y tomorrow, which would frustrate the vibe coder who'd feel that the agent doesn't "remember" what it was told yesterday.
So for people who look at the code the comments are obvious and completely superfluous, but for the vibe coder it's a way to ensure that their tiny (relative to the size of the code base) input is not forgotten.
The problem is the comments only make sense if you knew the original prompt in the first place. It'd be one thing if AI left a bunch of breadcrumbs reminding itself not do do Y, but when it makes a comment that only makes sense if you know about the original requirement not to do Y, to me it's more likely to trip up future agents than it is to help them.
A recent example I saw was an agent leaving a comment "// return an error here instead of panicking, as a panic will abort the process". Because likely the original human in the loop caught the AI putting a panic in there and told them not to, and then the comment to not do panics was placed in there. But to a future agent, it'll see that and think "ok, this comment must be here because we usually do use panics instead of returning errors, this place must be an exception", and now its context window is primed to think of using panics first.
It's pretty well-documented at this point that spending a lot of tokens explaining what not to do can actually increase the likelihood of an LLM doing that thing, especially when its context window is getting full.
It's like if you go to the grocery store and see a sign saying "Vegan tomatoes". It sounds fine until you think "wait, aren't all tomatoes vegan?" and now you start doubting yourself and start imagining what a non-vegan tomato would be.
Another semi-related issue is the tendency for LLM's to make up their own dumb little short-hand words for things that it has been talking about over and over in the context window. "The lock that prevents a user from being deleted while another thread is updating it" becomes a "user-fence", and now there's comments saying "// this function returns a user-fence", and I have absolutely no idea what that's supposed to even mean.
>They’re supposed to be exceeding human intelligence, at least at things like programming
This perception is a good part of why this market is irrational. LLM's aren't "intelligent". They do not reason, they are a very fancy kitbash of whatever it trains on.
Ad yeah, I'm not surprised that a lot of documentation on every bit of readable code online is awful. "Document the diff" sounds like an anti-pattern learned from people with an incentive to get as many PR's submmitted as possible, not make the most friendly documentation for people maintaining a project.
I have five enforcement mechanisms: 1000 line max edit, PR comment character limits (get to the point of your description), ISO 24495 conformance check, and enforced code line citation that must exist, be a function declaration for the start of all paragraphs and inline commentary must be three lines or less and inline comments contribute max 10% of the PR. Fail any of these, automatic PR denial with no human intervention.
This sound pretty good, but every single attempt to put an actual character limit meets incredible resistance on my team. ISO 24495 looks interesting, how do you enforce that? Do you have some agent?
Table of words LLM generated, Binary Searched on the output going forward and local skill/CLAUDE.md line with instruction to conform. The comparison then is pretty fast due to the word limitation rules. Also standardized PR format so a bunch of what a dev would usually communicate is just a series of checkboxes and a place for adding an optional link for "additional discussion" on slack as the escape hatch for people who like to waffle.
Binary Searched against a table of words. It's rough at first, but once you add contextual exceptions the false positives calm down. Also the CLAUDE.md file has an instruction to conform before even submitting the PR and there's a skill too for it to self iterate.
I told someone this week, who (or whose AI) chose to do a problem the hard way that it's usually a bad sign if you need more comments than code to solve a problem, and then suggested a couple lines of code that accomplished the same thing and used, are you sitting down? MEANINGFUL VARIABLE NAMES to document the purpose of each calculation.
I wonder if I can get a MacArthur grant for this epiphany...
Prune the comments? Instruct the LLM to print less comments (this one is genuinely hard though). What's really happening is that you don't have a strong enough review process (or a code standards process) to offset this. The one issue I see with this is that your team is almost certainly _NOT_ doing any kind of code review (especially if they're leaving comments like that). The other problem is that excessive comments actually harm LLM output, I've done tons of A/B testing, and pruning comments actually helps LLMs spot bugs, among other things.
I think your last sentence is getting close to the truth. You're no longer the audience for those descriptions. Other robots are.
I'm not saying that's good or bad because I don't know, but I think that's the idea of dumping all that junk into PR descriptions.
However, annoyingly, we still need to review those descriptions very closely, because the robots are trained to put a lot of weight into things they read in the documentation. And they tend tospresent loose speculation as fact. They often end up documenting some assumption that isn't true, then end up writing code as if it were.
Even worse, in a brownfield codebase that was once fairly light with comments, that's now being subject to these modifications, the insane amounts of commentary around the parts newly touched by AI lead to an excessive emphasis on those parts, for both human and AI readers (who think, well if this one part is commented so thoroughly, it must be unusually subtle)
Honestly, if you saved a ton of hours with the model coding for you, at least give me 30 minutes of your own words, show me you know what you're shipping, if you can't do that, then I don't know if I want to approve the PR. My first job we always did peer review in a meeting room when a PR looked a little too much, you can't exactly bring in GPT into a meeting so its a good time to ask simple questions about the change to ensure you understand it just as much as they do.
(usually) You're not in position of power to effectively keep that position. As comments aroiund - standing against will mark you as anti-ai luddite and will now end well for you, not AI-spammer.
I can already tell you for sure that those comments are a liability time bomb as soon as enough codebase changes and if the ai forgot to update those comments now it's gonna contextualise or hallucinate logic that doesn't make sense. It's work should be measured on the correctness and maintainability of what it generated, comments as soon as they become stale that's a ticking bomb.
This sounds easy in principle, but a half dozen of these sort sorts of massive PR’s per week is basically untenable. I’m not gonna read the hundreds of lines of added documentation to decide if they’re correct or not. The price of generating new words is just so much higher than the price of evaluating it that I can’t be bothered.
Just hit "deny." I've been training my co-workers that the AI-isms their "AI Assisted coding" do that some shit just isn't acceptable. I leave a comment and hit deny. It also helps that I control the policies on the repo and they can't merge in with a denial from anyone. So it's either a fix it, or explain why your work isn't getting done. My manager is also 100% with this.
I've denied for poor branch names and commits from AI. I've denied for too verbose of comments from AI. I've denied for parts of the code base being touched that are not relevant to the case they are working on (login isn't broken, your case is to add a check box in the settings pane, remove the changes made to login).
Pre-AI I wasn't fine with PRs with multiple features and touching irrelevant areas of the code base. Why would I be fine with it because my co-workers got new toys? You want AI to refactor a part of the codebase? Fine. Separate branch, new PR, and in the description, present an argument for it. Don't shoe horn it into something else. Also, I'm not obligated to hit approved on shit.
I may also be a bit privileged because I can be a pain in the ass to whole team. I may be slower, but I've got the numbers, my code is creating way less bugs then my "fast more efficient" co-workers.
When it's a problem, you should both expect to be unemployed fairly rapidly. Progress isn't going to stop solely because you want to pick 'excessively long comments' as a hill to die on.
You're really insistent on project your personal biases onto a person and company you do not even know the identity of.
Turns out not every team has the idea of "progress" being yet another iteration of "more code submitted = better code". Some people actually desire or need to make quality products.
Yea, its not one I exactly agree with. But it is what the team collectively as a whole said is something is important. So to the other comments acting like I am just being ridiculous. Everything I deny PRs on is something time and time again the team collectively agrees on when asked how code should look and the process and all of that. The team can choose at any time to change that and for some reason, enough people on the team when asked in a meeting if branch names matter a lot and if they should follow a certain format, its a yes.
Its not petty is, Im not changing our standards because people got hot new toys. These are code policies we've had. If your AI usage can not conform to them, that's on you, not me.
Why can't people just follow the guidelines. You really want to get into a fight over not following established and agreed upon guidelines and code quality standards?
> but a half dozen of these sort sorts of massive PR’s per week is basically untenable.
Actually, rejecting them is precisely what will make them easy.
"Sorry, the comments are so bad I'm stopping here. Please fix them and then I'll resume the code review."
You're giving everybody (including yourself) more work by:
1. Reviewing the code (even if you skip the documentation).
2. Letting too many abstruse comments in which everyone in the team will have to read.
3. Allowing the behavior to continue.
Become the bottleneck so the team can talk about it. If they decide this shouldn't be a blocker, just declare you won't review the comments going forward.
> "Sorry, the comments are so bad I'm stopping here. Please fix them and then I'll resume the code review."
This is also how I do code review of AI work on my projects. If the work is offensive to the point I can't complete the review, I simply reject the code and tell the AI why. Then it goes off and fixes it. This repeats until the issues are either gone or are small enough that I can just fix them myself and move on.
There is no need to be upset. Just iterate until it's right. If it's cheap to write, it's equally cheap to rewrite.
I am actually asking you to do your job. Pre-LLMs, if I got comments that were difficult to read in a code review, that PR isn't getting merged until they fix it. So: Review the docs. If it's that bad, just say "I don't understand these comments" and send it back.
What I’m trying to say is that they can generate many more hundreds of lines of code and comments than I can reasonably review. Maybe the comments do make sense they’re just five lines longer than they ought to be. Multiply that by 20 times and then add in 150 lines of documentation that is not technically incorrect.
Not to mention that the response to each review will come with its own set of new comments and new documentation. The ability of people to write things has exploded tenfold. You can’t out review the slop.
Every PR can be rewritten and re-architected on a whim.
Sure - but the volume is a separate problem from the quality of comments. Even if the comments were the best possible your complaint would still stand.
Tbh if the AI just followed the prompt to not add the comments, that'd be sufficient. It feels maddening and burnout inducing to tell it not to only to have it ignore that and you deal with the same problem every time without things meaningfully improving.
Your bosses don't want you actually reviewing it anyway. They want you to approve the PR. Just give them what they want.
I'm currently not working in tech, but I will again sometime within the next year or so, and I've been reflecting on my career in light of the recent AI madness. I think the biggest mistakes I've made over the last decade+ in tech as a software engineer have been caring. I've worked at small, medium, and large companies. Famous big names you've definitely heard of, less famous ones you probably haven't. In every case, in retrospect, as an individual contributor (non founder, non board member, etc) being personally invested in some outcome--quality, efficiency, cost, ux, customer value--is a mistake.
If you aren't actually in a position to change something, caring about it is futile. [edit] And I don't mean in the sense of "feeling empowered" or some such, but actually having the clout to steer the ship and make it happen. Very few people in a tech organization actually have that power, by design.
The industry wants to do away with code review, meaningful testing, computer security, and reliable services. Why swim upstream? You can't actually do anything about it so why try?
When I go back to work I'm going to do my 9-5 40hr/wk, smile, nod, punch the clock, and make the bosses smile or whatever. But I'll be damned if I'll ever give a shit again.
I think that's just too cynical when you apply it to the entire industry. I'm sure there are coding jobs where you are just a cog in a factory line but IME there are also those where a lot of things really are up to the individual contributor because either no one else has even given them any though or higher up defer to your judgement (which is part of what they are paying you for).
If you hold up the line by flagging quality issues, you will be seen as the root cause of the problem. I say this as someone who has been there and done that--I've tried to do something about code quality issues affecting my team's velocity. This resulted in a negative performance review. In another company I raised some concerns about a series of serious security issues that were not being handled. Again, management handled it in a retaliatory manner.
These things happened at companies that value their reputations as "good" places to work. Not Amazon. Not Google. I mistakenly thought fixing these problems would not only be possible, but also that it would be appreciated.
Maybe I'm tarring the industry with too broad a brush, but in my experience this is how it is: either you go along with the malfeasance or you're targeted. Being targeted fucking sucks. I'll never paint a target on my back again.
If that's what they wanted they'd mandate that process. They want the deniability of having you rubber stamp the PR. That way they can blame you when it goes wrong. There may be high trust teams, but I've never seen one firsthand, but my sample size is only N=5.
Before I became a SW engineer, I've worked in such teams (you "own" the quality, but they want you to do it so quickly that you can't really own it).
I left. I will always recommend finding a new job when you have dishonest management. (Dishonest by not admitting they are lowering the quality.)
Fortunately, none of my jobs since that job had that problem. They either allow good quality reviews, or they explicitly accept the technical debt that comes out of it and don't blame me for poor codebases.
(But then again, I make sure to probe these things during the interview process...)
> I make sure to probe these things during the interview process
I absolutely plan to do so throughly when I begin interviewing later this year. But I've been fooled before, so it'll take extraordinary evidence to get my hopes up, and I don't think I'll ever truly believe it again. There's always the possibility it isn't real or I'm misunderstanding something.
If you ever trust an employer you put yourself at a profound disadvantage. Employers are not so disadvantaged by placing (judiciously earned) trust in employees. That's because employers are companies, and companies are not people.
>The industry wants to do away with code review, meaningful testing, computer security, and reliable services. Why swim upstream? You can't actually do anything about it so why try?
Because habits beget habits, and in form imprint into your identity. I'm not the biggest fan of GPA fixation, but it does have the side effect of imprinting work habits (I won't say "ethics", because the extremes I saw peers go to to get A's is anything but). It doesn't necessarily imply mastery of your class, but your ability to adjust to someone's standards and meet them. Which is something that will follow you into the workforce, and roughly correlate with people who will meet the standards of their company.
If I don't give a damn about code quality in a place I spend a third of my life, why do I expect to give a damn when I want to work on my own project in the future? Even if I try those habits will wear into something I can call my own. This might be fine if your overall goals have nothing to do with your work; that you are fine just going through the motions and getting a paycheck to empower your non-tech hobbies or focus on supporting your family. But that's not the path I've chosen.
You can probably still write your own code to a standard of quality you're comfortable with, while conforming to the wishes of your employer. At least until you can't anymore, then you'll have to make a decision.
But in this case, we're talking about reviewing a deluge of AI slop. Other employees have been incentivized to generate all that slop. It's not your job as an IC reviewing said slop to push back and try to make it better. It's your job to approve the PR and get out of the way. If you do something else it'll come back at you in a bad way.
And probably if you're not generating a comparable volume of code, your output will be labeled deficient.
The bottleneck existed before LLMs. Amdahl's Law applies. Just because code can be produced 10x faster doesn't mean much if other parts of the flow can't be sped up.
As I said here and elsewhere: If management is concerned code review is a bottleneck, let management be aware that the process has to change. Either the human is not as thorough, or he uses some combination of his brain + LLM to conduct the review.
It's a basic fact: They have a machine that produces a lot of code, but don't have a machine to review that code. The bottleneck is obvious. I'd love to build planes for $1 too, but physics applies.
Management is not a logical formula. Management says all code must be reviewed, your coworkers are approving (rubber stamping) PRs 10x faster than you, why aren't you able to keep up? Why are you being difficult?
Again: I'm failing to see how this is different from pre-LLM days. If you have coworkers who are sloppy in reviewing, then you would have been a bottleneck compared to them back then as well.
Do you not have team meetings with the manager? Examine some of the PRs your coworkers reviewed, find the flaws, bring it up to the whole team, and get buy-in from the manager that he's OK with it. If he is, stop worrying and let the PRs through.
You can't keep up with the slop. And before you finish a first pass read on the wall of diff, another AI sloperator on the team has hit approve and the PR is merged.
Exactly this. Even if I spend a bunch of time requesting a review — and our team does respect each other enough to at least nominally respond to comments before merging — the update itself will be another thousand line diff from the original that requires again the same level of review or I just accept that it looks fine.
- PR descriptions should be human-written, you are a human communicating to another human. it should be limited at 4 bullet points, and maybe a "details" section in the (rare) needed cases
- in general, if you want human attention, produce human effort
I have my agent write up a summary of the diffs that land each day in my org. If there is something you interesting I’ll ask for an html explainer with code pointers and scan the code in parallel.
I wouldn’t say “post reading code” but it’s definitely trending in that direction.
I’d rather the agents put jumbo verbose descriptions in the PR description than in code comments TBH.
Is this in one of the skills or CLAUDE.md? This was happening in our codebase, but turned out it was interpreting an instruction to not add "what" comments as license to strip out comments.
Sometimes I have luck interrogating Claude on why it did something. It'll either point to a skill or agent file with the culprit, or it'll respond with some vapid nonsense and apologize.
I've definitely seen this. One of my least favorite parts of developing with AI is when I add print statements or small changes and the LLM removes them in the process of doing the next thing. I want to work _with_ the AI, not have it stomp all over my code.
When i first added "do not write comments" to my Claude.md, it started deleting all comments it came across. I yelled at it a bunch, eventually it got its md files aligned to where it's very clear: Claude does not write comments. Claude does not edit comments. Claude does not delete comments. Claude does not move comments. Only humans touch comments.
It's been working well for me for months now. If only I could convince the team to do it too
It's like people didn't realise that it was unmaintainable before and now we have a new level of unmaintainability. The insane amount of code produced means it's only maintainable with AI.
I think at this point all the info added by AI which certainly would be too much to read for every PR, it just serves the purpose of context for the next action. Which it could be good or bad depending on how big of a window of context you are working on
I've created myself a pre-commit harness hook to explicitly discard superfluous or too lengthy comments. Within code-review I also added comment review as blockers
Honestly, I’ve stopped caring about code readability for a few months now. I want the code readable _to the agent_ not so much to me.
I don’t trust it with code anyway - every feature needs comprehensive test, and then a live deploy on a real working test system before it is approved - I mostly measure success with - after deployment is it doing what it’s supposed to be doing.
It’s like “helping another team managing their work stream” experience rather than coding yourself.
Funny enough models seem to have personalities and the dis on each other - when I had an opus orchestrator dispatching fable workers, they would comment on how “unreliable” it was and it had “evidence to prove it” and fable thinks opus is too rigid and needs more hand holding… it really starts to feel like managing team egos and verifying work.
And I code scan mostly to just spot check if it’s not doing anything super stupid. But my goal is to make sure anything shipped is easy to change and fix, and every mistake has a test behind it so it doesn’t happen again.
I ship more problems, but they get discovered and fixed quicker. Before they reach prod of course.
And from time to time you do reorganisation and refactoring passes where I brainstorm how things could have been better with the help of evidence- chat sessions, tests, bugs etc.
It feels less like rigorous engineering and more like gentle gardening. Or like “project management” not “coding”.
Honestly given my age now I’m fine with that. Have enough “hard” projects under my belt (ORMs, sql parsers, etc) that I don’t feel I need to prove anything to anybody, but I don’t think that’s even relevant- the velocity change is … I guess around 5-10x for me - with provable metrics, so I try not to lent the good old days but figure out how I can now live in this brave new world and be happy with my work.
these companies/models charge by token usages, so as the model getting better at solving problem with "better" code (less code for accidental complexity), the comments/docs are just incentives for token usages
With one colleague, I was leaving PR comments and he would just put my feedback into the AI and paste its response. So I decided to cut out the middleman and now I just @cursor and tell it to trim unnecessarily long comments.
Of all the things in this thread - this is the one that grinds my gears the most. Colleagues that believe it’s ok to reply with unedited garbage when you engage with them as a human.
I don’t think we need to write code anymore unless we want to - but we DO need to be humans, and respect the time of other people.
One coworker had their agent respond to me, with "from Claude : robot emoji:" at the end, that made me mad.
Then another coworker just pasted the Claude response with no signature and no comment and no context as if they had written it themself. That made me livid. I used to like that guy. No respect anymore.
In your CONTRIBUTING.md add a human-first readability rule. Ordinary English accessible to your average person - for extra irony ask the agent to generate the rule content.
When technical language is necessary instruct the agents to use ASD-STE100 Simplified Technical English.
I'm... Actually fine with that. In one direction. I use AI to fill in forma and usually it has really good pointers. I do not trust it to do it itself, but it does simplify things quite a bit.
Is it really, or do you just think so and it could actually mislead you and your LLM the next time? In my experience, the information in the comments tends to be quite redundant, often even with other comments in the same file
Personally I'm criticizing every single comment until I quit the industry or my coworkers convince their Claudes to shut up.
Maybe I'll sneak in a change to CLAUDE.md telling it to stop
But half the time these paragraph-long comments don't even make sense, or refer to a previous iteration of the branch that has since been deleted and nobody including the author ever looked at
> My coworkers continue to dump hundreds of lines of AI documentation in every PR and every other line of code has between one and ten lines of AI generated comments, talking about the real unlock and how things are byte for byte identical on the load bearing path or how the acceptance ladder is misleading.
They're just helping you understand the whole picture!
> Features are coming out and metrics are improving, but we’re basically in a post readability code base, with the occasional performative comment about a variable name.
You futilely grasp for control and it eludes you. The Way is to ride the tides of life, move with the forces that shape you. Your code base is in the hands of the Machines now.
The number of times I've seen phrases of the form "(ingestion|main|ingress|success|designated} path" in workslop docs recently is frankly intolerable.
Last week someone sent me a 50 page doc with a proposed update to a (small) system architecture. It was so boring that it took me all day to read it, but the information density was low enough that it could have been written (by the author instead of a chatbot) in like 3 pages. Endless tables comparing the "recommended path" against stupid strawman implementations, and repeated "DO NOT send packets directly to the ingress, ensure they go through ..." statements that were totally unnecessary. Utterly mind-numbing thought-terminating slop.
It's actually insanely difficult to get LLMs not to produce comments. Even with explicit "NEVER LEAVE ANY COMMENTS WHATSOEVER", they still do, across basically all providers.
No problems with GPT-5.6 Sol here. I have an agent file that says, among other things, only to document purpose and intent, not just what the code does, and not write obvious comments. It's been so effective that it often doesn't comment anything at all, including some stuff that's so niche that it must be explained carefully. As a result, I've had to pull back a bit and tell it explicitly which areas to actually add comments for.
Every single time Claude wrote a comment i replied in all caps FUCK YOU CLAUDE I TOLD YOU NEVER TO WRITE COMMENTS, WRITE IT DOWN SO YOU NEVER FORGET: YOU DO NOT WRITE COMMENTS. ONLY HUMANS WRITE COMMENTS. and after like 3 or 4 rounds of this it finally stuck and i haven't seen a Claude comment on my personal machine in months.
Features are coming out and metrics are improving, but we’re basically in a post readability code base, with the occasional performative comment about a variable name.
I don’t really know how to address this situation or if it needs addressed. I certainly don’t read the long-winded AI comments or the AI documentation, but perhaps it’s useful for the AI on its next pass.