Comments should explain WHY. Why this needs to be done. Why we’re doing it this way instead of that way. Why this works when it looks like it shouldn’t. Why the business requires this rule/check/transformation/etc. why you would want to pass this param.
Comments that explain WHAT the code does are redundant if the code is reasonably self-documenting (as it should be).
Javadoc style docstrings should also be redundant, but sometimes it’s worth a comment to explain what a particular param actually does or is for, especially if it’s at all esoteric. `frobnicate_quux` is all well and good except I have no idea what a quux is or why I would want to frobnicate it when calling a function to send an email.
Unfortunately, there are a lot of tutorials in the training corpus, and tutorials are one of the few places where WHAT comments are important. LLMs have a bad habit of commenting like a tutorial.
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........
Comments should explain WHY. Why this needs to be done. Why we’re doing it this way instead of that way. Why this works when it looks like it shouldn’t. Why the business requires this rule/check/transformation/etc. why you would want to pass this param.
Comments that explain WHAT the code does are redundant if the code is reasonably self-documenting (as it should be).
Javadoc style docstrings should also be redundant, but sometimes it’s worth a comment to explain what a particular param actually does or is for, especially if it’s at all esoteric. `frobnicate_quux` is all well and good except I have no idea what a quux is or why I would want to frobnicate it when calling a function to send an email.
Unfortunately, there are a lot of tutorials in the training corpus, and tutorials are one of the few places where WHAT comments are important. LLMs have a bad habit of commenting like a tutorial.
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.
[dead]
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.
Too much for sure, and often ignores instructions to not leave obvious 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........
I have something to the effect of ‘no narrative comments’ in my Claude.md that mostly sorts this out
[flagged]
[dead]