A lot of people way “you must comment your code.”
It really boils down to the last sentence: “Comment what the code cannot say, not simply what it does not say.”
There are various reasons why people demand comments:
- They are not fluent in the programming language or don’t know enough to read the code. There is nothing wrong with the code – the readers simply don’t know enough to understand it.
- The code is broken in some way and you need the comment to make sure people don’t break it even more.
- The comment explains something that no one will see from the code.
Only #3 is a valid reason for comments. #1 is just adding noise for people who shouldn’t touch the code anyway. #2 means you should refactor the code to make its intent clear – adding comments will only make things worse.