> But worse, many comments include in the moment reasoning like "added parameter bar because we can no longer use the frob to automatically derive bar". That's stuff for a commit message, or just a mental note, and absolutely not for comments.
I've noticed this a lot, and before your remark I couldn't put my finger on what was wrong. Now I know: Claude is writing its thought processes and maybe parts of the conversation it had with you as comments in the code!
I always end up manually trimming those comments, which is cumbersome.
It also loves to reference internal notes and scratch docs that never go into source control, so a reader will have no idea what it’s talking about. For example:
Ok but nobody reading the source code knows what this doc is. You don’t have to cite it.