Writing good (no) comments

Have you ever wrote something to someone else read? Of course you did! We are always writing something to someone, even for ourselves. And this is how I want to start defending my idea: write a piece of software is just like write a simple text, an article, a paper or even a book. You write it, and you write it clear, so anyone (even yourself) can read it later.

Let’s see an example of that. Suppose your are writing an e-mail to a friend of yours. Do you write a comment about what you wrote? Let me show you:

“Dear ‘Friend of Mine’, how are you? Have you started reading that book? (comment: I’m talking about the book of John Doe). I have just finished the reading of that other book (comment: I’m talking about Alice Cooper book) and I’m wondering if I can go there (comment: your house) and get another book.“

Will your friend understand what you wrote? Probably yes! But, is it a good reading? Can you read smoothly? Probably not! Why can’t you put all the information, that are in the form of comments, inside the text itself? Let’s see how it could be:

“Dear ‘Friend of Mine’, how are you? Have you started reading John Doe’s book? I have just finished the reading of the Alice Cooper one. And I was wondering if I can go to your house and get another one.”

If you are reading this blog you are probably a developer! And if yes, you have also started to get what I’m trying to say here. Writing software is just like writing a piece of text, the only difference is that your are writing instructions, but you are writing it in a different language.

There is also a problem, most of us write code in a way that is enough for the computer to understand. If it compiles, than the computer will understand and the code is OK. That’s not true! Because the computer is not the only one that is going to read that “text”. If your software is not dead, you will read the source code later, other developers will, and even good testers will probably want to read it too.

I like a sentence that I’ve read in uncle Bob’s book, Clean Code, that says:

“The proper use of comments is to compensate for our failure to express ourself in code.”

He means that if we need to write some comment on our code to explain what we are doing, it means that we are not skilled enough, on the language we are using, to express ourselves. Read uncle Bob’s book awoke me to care about my code. But getting this point of view, about self expression on source code, was the most valuable jewel I’ve found on it.

I can’t dive into all the bad things about writing comments, that would be a “copy” of his book. So I prefer to encourage you to read the entire book, specially the chapter 4.

I also wanna close this post citing Steve McConnell:

"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?'"