maandag 4 juli 2011

Commenting code

Ever had such a moment?

2010-01-02_1809

This Slashdot story (Myths About Code Comments) has the following comment:

Clean code tells you how, good comments tell you why.
Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.

The author calls it a cliché but it makes a lot of sense. So what happens when you talk about the code, or more specific, explain what the code does?

From A Lesson In Low-Defect Software
- or -
A Journey From A Quick Hack
To A High-Reliability Database Engine
and how you can use the same techniques to reduce
the number of bugs in your own software projects (PDF)

Why Put Comments In Code?

  • 1) Make the code easier to read
  • 2) Engage the linguistic side of your brain
The second point is especially compelling.

What does this mean? The document makes some bold statements about left and right sides of the brain. However it is hard to find documentation that supports the claims. The difference between the how and why does make it easier to understand the need for commenting code properly. We all know how the quick brown fox jumps over the lazy dog, but why the dog is lazy might need some commenting