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.
This entry was posted on Thursday, March 1st, 2012 at 10:27 and is filed under Software. You can follow any responses to this entry through the RSS 2.0 feed.
You can leave a response, or trackback from your own site.
Dark Views
Commenting Code
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:
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:
Rate this:
Share this:
Like this:
Related
This entry was posted on Thursday, March 1st, 2012 at 10:27 and is filed under Software. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.