10 ms·
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 comme
by LPisGood 2mo ago
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.
- mawadev 2mo agoJust wait until you see vibe contracts, vibe requirements and vibe legal documents
- RealityVoid 2mo agoI'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.
- EastSmith 2mo agoI dump AI output in PRs, because it ads context for the AI reviewer.
- moltar 2mo agoI address it with AI. Write REVIEW.md. I have CC check itself pretty well. I also put into agent/claude/review instructions to write using simple English skill and humanizer skill. Then not to write redundant comments. It’s not perfect but definitely catches lots of slop.
- rfgplk 2mo agoIt'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.
- atombender 2mo agoNo 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.
- deleted 2mo ago[deleted]
- queenkjuul 2mo agoEvery 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.
- lluisantoni 2mo agoI assume you are already using CLAUDE.md to give these instructions and still not working?
- queenkjuul 2mo agoClaude writes it's own markdown files when i yell at it, i don't touch the config manually
- Fordec 2mo agoI 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.
- LPisGood 2mo agoThis 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?
- Fordec 2mo agoTable 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.
- CSMastermind 2mo ago> ISO 24495 conformance check How do you enforce that?
- Fordec 2mo agoBinary 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.
- rfgplk 2mo agoPrune 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.
- noman-land 2mo agoHave 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.
- corndoge 2mo agoFighting the ocean is futile
- trip-zip 2mo agoSo is completely eliminating litter, but I still pick it up when I pass it.
- noisy_boy 2mo agoEverybody 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.
- abustamam 2mo agoI 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. It's a race to the bottom, for sure.
- giancarlostoro 2mo agoHonestly, 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.
- fragmede 2mo ago> you can't exactly bring in GPT into a meeting They totally gotta be doing that at OpenAI. Meeting invitees: You, co-workers, GPT 5.6.
- giancarlostoro 2mo agoWell yeah, they'll keep burning the VC bucks.
- febusravenga 2mo ago(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.
- golergka 2mo ago> perhaps it’s useful for the AI on its next pass Yes, that's the entire point. And it is extremely useful. Why wouldn't I want this?
- BeetleB 2mo agoIt's a code review, right? Give feedback that about the docs and block merging till the issue is resolved.
- Gigachad 2mo agoYou 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.
- LPisGood 2mo agoExactly 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.
- account42 2mo agoAt that point maybe go looking for a company with a better work environment.
- deleted 2mo ago[deleted]
- LPisGood 2mo agoThis 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.
- BeetleB 2mo ago> 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.
- sebastiennight 2mo agoAm I the only one who's had Claude almost systematically remove human-written comments? It might be touching one line of actual code in a file, and take advantage of it to remove 20+ lines of actual useful comments. Everybody is talking about the opposite, so I'm wondering if this is rare.
- MattGrommes 2mo agoI'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.
- aaaronic 2mo agoDo you think it's actively deciding to remove them or just not noticing you added them and then overwriting? I ask because when I started informing it I made personal edits, it stopped doing this kind of thing so often and let me work _with_ it more. My saved prompt now says never to assume a file has not been edited since the last time it was read between prompts.
- panopticon 2mo agoIs 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.
- queenkjuul 2mo agoWhen 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
- cuddlyogre 2mo agoYou forgot the smoke tests that passed.
- donkeyboy 2mo agoSo many smoke tests in every PR i make with AI. Not that i mind, I just find that phrase funny.
- joshmoody24 2mo agoMy 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.
- moffkalast 2mo agoI 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.
- nicknow 2mo agoI 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.
- aaaronic 2mo agoMy "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!
- koyote 2mo agoIt'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...
- preg_match 2mo agoI 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.
- Taek 2mo agoI 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.
- mrweasel 2mo agoThat's is something I did not consider, the model using the existing comments as input. Comments that it may itself have written.
- dimgl 2mo agoCongratulations: now only AI can iterate on your codebase!
- broast 2mo agoMost ai output is meant for other ai's to read, in my experience. The humans job is to compress it for humans
- rbongers 2mo agoTwo 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.
- ninkendo 2mo ago> Document what's there, not the diff 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.
- eru 2mo agoIt's a bit weird, because that seems like something that approximately the same in every code base, so should be relatively easy to train generically.
- johnnyanmac 2mo ago>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.
- 2mo ago
- hinkley 2mo agoI 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...
- hrk5 2mo agoI 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
- theptip 2mo agoI 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.
- the_af 2mo ago> I don’t really know how to address this situation or if it needs addressed. My worry is that after several passes this compounds and starts introducing errors or biases, a bit like in the "telephone game" children play.
- apical_dendrite 2mo agoWith 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.
- sailfast 2mo agoOf 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.
- queenkjuul 2mo agoOne 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.
- kristjansson 2mo agoAnd 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.
- LPisGood 2mo agoI 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.
- fireflash38 2mo agoI 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.
- eru 2mo agoTry property based testing perhaps.
- LPisGood 2mo agoI’ve heard of this, but I’m not really sure at all how to even get started. Are there any good guides out there?
- eru 2mo agoMany people like https://fsharpforfunandprofit.com/series/property-based-testing/ https://fsharpforfunandprofit.com/series/property-based-test... In this day and age, https://hypothesis.works/articles/claude-code-plugin/ https://hypothesis.works/articles/claude-code-plugin/ might be useful.
- fnord77 2mo agoI always as for CONCISE documentation. still get walls of text sometimes
- CuriouslyC 2mo agoI'm looking forward to when AI labs focus more on conciseness of code and writing.
- seer 2mo agoHonestly, 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.
- hbcdbff 2mo ago> I’ve stopped caring about code readability for a few months now. […] I don’t trust it with code anyway If you don’t trust it with code, surely you need the code to be readable so you can understand what it is writing?
- kqr 2mo agoI 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.
- anematode 2mo agoEven 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)
- kstenerud 2mo ago[flagged]
- bitwize 2mo ago> 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.
- Bombthecat 2mo agoYou use AI to summarise it! That's the way to go lol
- 72deluxe 2mo agoIt'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.
- eithed 2mo agoBe the change you want to see :) 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
- thepra 2mo agoI 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.
- queenkjuul 2mo agoPersonally 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
- ukj 2mo agoIn 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.
- miraculixx 2mo agoStop accepting these PRs. Ask for a personal 1:1 explanation. Make it the submitter's problem, not yours.
- a_c 2mo agoIf you are not mindful, the tests it generates is just a re-implementation. Nothing was tested but every future change needs to modify two places
- cade 2mo ago[dead]
- Exolon 2mo agoThe 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.
- deleted 2mo ago[deleted]
- cosmosz 2mo agothese 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
- davidguetta 2mo agoAt my work i put these simple rules - 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