Should you comment your source code?

There’s been a lot of debates on this one.
The answer is neither no or yes, but it’s a lot closer to no :)

##The 1st part: NO

Nowadays, I see lots of teachers teaching people how to comment the code. And it just doesn’t feel right. The code they’re writing usually doesn’t look readable, so they put a comment above every few lines.

In the most cases, people are missing two main points:

1. Write the code that is self-explainable
2. Don't write code for macihnes. Code is for humans.

Those are not my words. They’re already written in some books, like “Refactoring” (M.Fowler), “Clean Code” (Robert C. Martin),… If you’re a professional programmer, you should read them.

The main fact is that the code needs to be documented. It’s on you to choose the way how you want to do it. Writting comments isn’t the only (and in the most cases - the proper) way of doing it; the code should speak by itself.

{% blockquote R.C.Martin http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 Clean Code %} The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent. {% endblockquote %}

Let’s see an example:

int a; // number of participants

A proper way:

int numberOfParticipants;

Or, the most common one:

int i, j;
int c[8][8] // a checkboard

for(i=0; i<8; i++) {
	for(j=0; j<8; j++) {
		c[i][j] //do something
	}
}

A proper way:

int numberOfRows = 8;
int numberOfColums = 8;
int checkboard[numberOfRows][numberOfColums];

for(int row = 0; row < numberOfRows; row++){
	for(int column = 0; column < numberOfColums; column++) {
	
		checkboard[row][column] //do something
	}
}

The other problem around is that some programmers are used to write big functions.
If you can’t tell what the method is doing from it’s name, that’s fine, you peek in.
But if you can’t tell after a minute or two of looking in it, then something’s definitely wrong.

{% blockquote %} FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY. {% endblockquote %}

Extract methods.
Give the proper names to objects, variables, functions.
They should be named by what they do.
And they should not do more than their name is saying.

My favorites are when someone names the variables like myDict, myNumber, theThing, aString,… Your myDict is a dictionary with intention. So name it restaurantDict if it represents a restaurant. Or if it was myArray with many restaurants, name it restaurantsInDicts.

If you followed all this guidelines, your code should need almost no comments.

##The 2nd part: YES

This will be a short one.

Basically, there are some cases when you have a nicely documented code, but you needed to do something that may not seem obvious on the first look.
So you put a comment in saying why have you done it that way, to save the other programmer’s time.

Imagine you’ve put a monitor on a corner of the table. You needed to do that because the cables were too short.
You could end up with a method like moveMonitorBecauseCablesAreShort, but sometimes you haven’t written the class you’re using, or it would just add the unnecessary complications in the code.

Then you write

// the monitor is here because the cables are too short and it sometimes turns off

The other reason for commenting is when you’re writting a public API for others. You can write something like Javadoc, just keep in mind to reduce comment sizes and improve the namings.

THE END

Here’s the best comment ever :)
(maybe you’ve read it already somewhere):

#
# Dear maintainer:
#
# Once you are done trying to 'optimize' this routine,
# and have realized what a terrible mistake that was,
# please increment the following counter as a warning
# to the next guy:
#
# total_hours_wasted_here = 25
#