Step 16: A Comment on Comments ~ Cal Evans

This is the Sixteenth Step towards gaining the Programming Enlightenment series. If you didn’t learn the Fifteenth Step, read it.

“Real programmers don’t comment their code. If it was Hard to Write, it should be Hard to Understand”

~ Tom Van Vleck

“Good Code is self-documenting”. How many times we hear this or repeat this as a daily mantra. It’s a cliché.

So, should we never comment our code? Yes/No (Why explained later.)

But, should it be self-documenting? Yes

What is a Self-Documenting Code ?

Remember Step 11, if not go ahead, refresh it.

float a = 9.81; 
float b = 5; 
float c = .5 * a * (b^2);

What can you reason for all of these constants? Can you guess what they represent.

Now, consider the following

float gravitationalForce = 9.81;
float timeInSec = 5;
float displacement = (1/2) * gravitationalForce * (timeInSec ^ 2)

Do I even have to ask what those constants mean? That’s the power of self-documented code.

Code that allegedly explains itself without the need of extraneous documentation, like flowcharts, UML diagrams, process-flow state-diagrams, etc is Self-Documenting Code.

If it’s Self-Documenting Code, we need no comments?

Consider the scenario again.

float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Would you be satisfied with this code, or the one which was self-documenting.

This should be one good reason enough for you to not add comments but rather have a self-documenting code.

When you should comment?

Comments aren’t necessarily evil.

Why we should comment is discussed in the following Seventeenth Step.

TL;DR Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer.

~ Steve McConnell

Go to the series.

Go to Fifteenth Step.

Go to the Seventeenth Step.

References:

• 97 things Every Programmer Should Know ~ Git Book
• 97 Things Every Programmer Should Know ~ Paperback
• Self-Documenting Code ~ Wiki.c2
• The good-bad and the ugly of comments ~ Medium