Code comments: Good, Bad and Ugly

“Good code is self-documenting.”

You must have heard this phrase but what exactly it means?

It’s a Cliché.

This truth has been abused too much that most people who have heard about this phrase have no idea what it really means.

Is it really true? Yes
Does it mean you should never add a comment on your code? No

Nowadays there is a big confusion of whether we should comment code or not or to some extent. Some developers write way too many comments or no comments at all.

Let’s talk about what exactly is the best practice.

First of all, all programmers should write code which should not require adding comments; It should be self-explanatory (using variable names, function names, class names..). It doesn’t mean we should not add comments in code but in a good way which I will explain below.

Basics of commenting your code:
- Make them brief.
- Keep them relevant.
- Use them liberally, but not redundant.

There are so many different types of comments but I will talk about two types of comments in your code just to give you an idea:
1. Documentation comments
2. Clarification comments

Documentation comments

Bad

Now look at the example above, the comment section is absurdly long. This is not a good habit, no one is likely to read through it. Unless your code is some form of API documentation. Think again about long comments of API documentation because they are most probably change accordingly when you will change your source code. A better way is to use a documentation comment library which you can find many online.

Do not use that much long comment text to explain your code. It’s boring and no one is going to read through it.

Clarification comments

Let me give you two examples and then let’s decide what is a simple and good approach.

Bad

Good

Do you really want to be responsible for robbing the joy of other future coders of reading and understanding the beautiful code rhyme? Keep your code simple and let others understand. If you have to explain your logic then do not explain line by line.

The Ugly

To be able to better explain this part let me give you my real-life example.

Once, during my master’s studies, I was working on a semester project together with my friend and we stuck on resolving one error in our code. We asked another friend for help in resolving that specific error. He started debugging the issue and after a few hours of struggle he was able to resolve that issue but out of frustration, he left a comment line above that piece of code. Here is that comment: // F*** you

Very next day we successfully submitted our running project without noticing that piece of comment. We were called by our head of department to explain our intention of writing that comment (Professor thought we indirectly wanted to say to him). Funny story for you but not for us.

Never write that type of comment. Below are a few more examples:

/* This class was just a workaround. $developer_name f***ing idiot */

Another example:

// This function looks like it is written by a third grade.
// Check my well-written function, and don’t repeat your stupid logic like this.

These things may seem funny or may release frustration but in reality, think about this for a moment. Is this really a way to express yourself? Do you really want to be that much unprofessional?

Never do this.

If you enjoyed this article then smash the applause icon a couple of times for appreciation.
If you have any queries or if you want to correct me at any point then reach me on Twitter or Linkedin.