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!

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.

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.

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.

Be 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

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.

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

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.

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.

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.

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.

Congratulations: now only AI can iterate on your codebase!

It's a code review, right?

Give feedback that about the docs and block merging till the issue is resolved.

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.

You forgot the smoke tests that passed.

Most ai output is meant for other ai's to read, in my experience. The humans job is to compress it for humans

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

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

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.

I'm looking forward to when AI labs focus more on conciseness of code and writing.

I dump AI output in PRs, because it ads context for the AI reviewer.

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.

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

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

Just wait until you see vibe contracts, vibe requirements and vibe legal documents

You use AI to summarise it! That's the way to go lol

I always as for CONCISE documentation.

still get walls of text sometimes

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

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

[flagged]