Commenting Code

1. March, 2012

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:

  1. 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.
  2. The code is broken in some way and you need the comment to make sure people don’t break it even more.
  3. 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:

Leave a Comment » | Software | Tagged: , , , | Permalink
Posted by digulla