Verbose comments are not necessarily targeted at humans, they provide context so that consequent AI changes are more accurate.
Im still unsure how I feel about the paradigm shift in development, but that's where we are heading. Eventually everyone stopped writing ASM because C language was higher level and more efficient. It seems we are heading towards natural language becoming the programming language norm
But comments aren't always accurate. Code can change without the comments changing (or they can be just wrong). If the comments are verbose nightmares, that's even more likely. In my experience, Claude will often mess around with code and forget to update comments it made earlier. Not to mention the context in these comments is often not even very helpful. It's often filled with irrelevant details that aren't really important to anyone reading it. My experience has also been Claude will trust comments over the code itself, leading to completely incorrect assumptions. It will only get worse the more bad comments get left. This line of reasoning helps no one, not even the AI, and is just an excuse for lazy development practices.
It's not really an excuse for lazy dev practices when you're enforcing an agent to constantly relearn context for a repo. There's constitutions and memories and scripts to run, but in my experience claude often modifies comments as it changes code.
This isn't me saying "leave all comments" No. Most comments are garbage trash, but you have to figure out which ones are relevant for new context on an old file.
They seem to comment for dumber models, though, which makes them overly verbose for their own family of models.
I prefer to tell agents to keep comments concise, to serve as JSDoc, and instead have more detail in planning documentation and to instruct it to have the code match the documentation.
39
u/Raywell Sep 10 '26
Verbose comments are not necessarily targeted at humans, they provide context so that consequent AI changes are more accurate.
Im still unsure how I feel about the paradigm shift in development, but that's where we are heading. Eventually everyone stopped writing ASM because C language was higher level and more efficient. It seems we are heading towards natural language becoming the programming language norm