A lot of people way “you must comment your code.”
Kevlin Henney wrote an excellent piece on this topic in 97 Things Every Programmer Should Know: Comment Only What the Code Cannot Say
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.
Related articles:
Commenting Code
1. March, 2012A lot of people way “you must comment your code.”
Kevlin Henney wrote an excellent piece on this topic in 97 Things Every Programmer Should Know: Comment Only What the Code Cannot Say
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:
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.
Related articles:
Share this: