Comments vs. Self-documenting

Tags: , , , ,
Recently I had few talks with my co-workers about the "problem" of writing code comments.
There ware arguments like: "When you use Python you don't need to write comments because it is Self-documenting language". But is it really true? Or the "problem" in fact is only inborn human laziness? What is the purpose of comments?

Here is copy/paste fragment of C++ tutorial about... the comments.

At the statement level, comments should be used to describe why the code is doing something. A bad statement comment explains what the code is doing. If you ever write code that is so complex that needs a comment to explain what a statement is doing, you probably need to rewrite your code, not comment it.

Here are some examples of bad line comments and good statement comments.

Bad comment:
// Set sight range to 0
sight = 0;
(yes, we already can see that sight is being set to 0 by looking at the statement)

Good comment:
// The player just drank a potion of blindness and can not see anything
sight = 0;
(now we know WHY the player’s sight is being set to 0)

Bad comment:
// Calculate the cost of the items
cost = items / 2 * storePrice;
(yes, we can see that this is a cost calculation, but why is items divided by 2?)

Good comment:
// We need to divide items by 2 here because they are bought in pairs
cost = items / 2 * storePrice;
(now we know!)

Programmers often have to make a tough decision between solving a problem one way, or solving it another way. Comments are a great way to remind yourself (or tell somebody else) the reason you made a one decision instead of another.

Good comments:
// We decided to use a linked list instead of an array because
// arrays do insertion too slowly.

// We're going to use newton's method to find the root of a number because
// there is no deterministic way to solve these equations.

Finally, comment should be written in a way that makes sense to someone who has no idea what the code does. It is often the case that a programmer will say “It’s obvious what this does! There’s no way I’ll forget about this”. Guess what? It’s not obvious, and you will be amazed how quickly you forget. :) You (or someone else) will thank you later for writing down the what, how, and why of your code in human language. Reading individual lines of code is easy. Understanding what goal they are meant to accomplish is not.

To summarize:
  • At the library, program, or function level, describe what
  • Inside the library, program, or function, describe how
  • At the statement level, describe why.