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 :)

Part 1: No

The first school of thought focuses on how to comment the code. The code provided in most of the examples usually doesn’t look very readable, so comments provide required context and make the code more readable.

In 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.

These ideas come from books like “Refactoring” (M.Fowler), “Clean Code” (Robert C. Martin) and probably a bunch more that I haven’t read.

The main problem 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.

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.

—R.C. Martin, Clean Code

Let’s see an example:

int a; // number of participants

A self-documented 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.

Functions should do one thing. They should do it well. They should do it only.

—R.C. Martin, Clean Code

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 variables named like myDict, myNumber, theThing, you got the gist. 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 follow these principles, your code should need almost no comments.

Part two: Yes

There are cases when your code may not seem obvious at the first look. You could be working with a language or a library that has short letter naming conventions, or it’s an archaic tool with a bad API. So you put a comment in that explains why you done it that way, or even what is going on in case of a bizzare API (like awk for example).

Imagine you’ve put a monitor on a corner of a 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 noise in the code.

// the monitor is here because the cables are too short and it sometimes turns off
monitor.move(10, 5)

To wrap it up, here’s a classic (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
#