I can really recommend the book Clean Code, here is a summary: https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988c...
You'll ask it to do something and it'll comment the code with an answer to what you asked it, rather than just explanatory comments to whoever comes after.
There's also a second issue that if the code is actually incorrect, the comment can nevertheless bolster the case for it.
Not to Claude – its own, old comments have helped me/it solve new issues on more than one occasion.
//add returns the sum of x and y
//per section 2.1 of addition-implementation-plan.md sum is designed as the seam for user addition interfaces.
//previously sum added numbers, now it adds numbers
def add(x, y):
return x + yIt felt like it was commenting on the diff sometimes instead of what the code was doing.
Claude very often litters code with comments about decisions that were made within a single session/pull request, its just noise.
It writes out stories describing what isn't there or what used to be there. It's usually not helpful, just noise. It also likes to write it in very verbose AI-styled prose.
Dude, just talk about the current state of the code!
Useful for the LLM to know the "why", but not something a human would do, unless it's a very critical and confusing part of the code.
Fewer AI-generated comments is generally a good thing.