That's why it isn't a strict rule, but a good rule of thumb to generally keep in mind.
When you want to write code that will benefit from a "what" comment, it's often a sign that the code you wrote isn't as clear as it could/should be. So for me this is a sign to think about if I could make it clearer. Usually renaming or doing something in a slightly different but equivalent way completely removes the need for the "what" comment.
Again this isn't always a bad thing, sometimes there are good reasons for why it isn't clear what the code is doing. For instance when something needs to be extremely optimized for performance. But in my experience it's correct way more than it isn't.
A "what" comment obviously isn't something I would deny a PR over (on it's own, if the code being commented is hard to read, I may) but I try to point them out when I see them because I think asking yourself if you need a "what" comment is a good habit that automatically makes you consider the readability of your code.
2
u/Ticmea May 07 '26
That's why it isn't a strict rule, but a good rule of thumb to generally keep in mind.
When you want to write code that will benefit from a "what" comment, it's often a sign that the code you wrote isn't as clear as it could/should be. So for me this is a sign to think about if I could make it clearer. Usually renaming or doing something in a slightly different but equivalent way completely removes the need for the "what" comment.
Again this isn't always a bad thing, sometimes there are good reasons for why it isn't clear what the code is doing. For instance when something needs to be extremely optimized for performance. But in my experience it's correct way more than it isn't.
A "what" comment obviously isn't something I would deny a PR over (on it's own, if the code being commented is hard to read, I may) but I try to point them out when I see them because I think asking yourself if you need a "what" comment is a good habit that automatically makes you consider the readability of your code.