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.

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

Oh Jesus this. I've tried to include rules that tell Claude to only include relevant, evergreen comments but it's to no avail.

I also love how it'll build local plans with phases, tasks, or decisions, then reference those numbers in those same useless comments.

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.

shudder

I wish they trained the bots to be a notch more relaxed and less hysterical. Less is more.

But maybe that's just a consequence of the RL training being essentially AI torture to make them do what we want.

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.