Claude's code comments – too much or just enough?

Well, a good programmer doesn't leave code comments in production code.

This is basic from school.

Why not?

Two reasons: First, you are telling an attacker, "Look, my code works like that, and this function does that, etc., etc." Without comments, let the attacker read and try to understand everything alone, if he can.

Secondly, it's easy to copy totally or partially, you spent hours coding and anyone can say "Oh look a nice function; it's what I was looking for."

The normal behavior should be keep comments for yourself in a development code copy delete all comments for production.

there's a difference between comments above code (documenting the purpose of a class/function...) and comments inside code (documenting the implementation or design).

I treat comments inside code as smells. They exist sometimes because the author wanted to say something else but was prevented from doing it because of existing conventions, sometimes because a piece of code is difficult to understand, sometimes because a large piece of code has multiple responsibilities. For things like that, I tend to clean up the code to make the design more intention revealing and break large pieces of code into smaller pieces with appropriate names. I tend to document behaviour using unit tests (where the unit test has the name that would be in the comment). This was a rule before claude code, and it still is for us.

In general, this leads to better code, that's easier to understand, manage and maintain. It also leads to functional decomposition that's easier to test than a large blob, so fewer bugs.

We have linting rules preventing claude from leaving comments inside code, and forcing it to apply these refactorings. The one to write tests to document behaviour instead of just commenting it is especially useful as there's proof that the code is actually doing what the comment suggested, and ongoing checks that it still does that. a comment may become stale easily without you noticing.

as for the reason why claude is doing it, my best guess is training material included lots of comments.

If without the exccessive code comments and emojis how would Anthropic earn those money from you? more code and commnets meaning more token usage. So........

Too much for sure, and often ignores instructions to not leave obvious comments.

I have something to the effect of ‘no narrative comments’ in my Claude.md that mostly sorts this out

[flagged]

[dead]