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 KnowComment 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 Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 339 other followers