Does your code require Comments?

Do you comment your code often? If the answer is yes, you need to rethink on how you could avoid or reduce the number of times you write comments? Why?

There is nothing wrong in commenting the code, what’s wrong is writing the code that requires comments to explain what it is doing. As a developer, instead of focusing on writing comments, one should strive for writing self-explanatory code.

Take a look at below C# code snippet, 

It would be very difficult to understand the code if that comment wasn’t there. So how do you avoid commenting if it is difficult to understand the code without it? Makes sense Right? Ok, now take a look at below code snippet.

With slight modifications, like putting the block of code inside the function with meaningful name, I’ve managed to avoid the comment, the reader of the code should not get confused now. There is another problem with the commented version of the code, what if the requirement changes? Like remove all the spaces, in this case you have to change your comment also, while in the code without comment the developer can just rename the function. It is very difficult and expensive to maintain comments. With the changing code bases if the comments aren’t changed, they can misguide the reader of the code.

You cannot always avoid comments, below are the points where I feel the comments are necessary

      1)      If you are a library developer :

And your library is going the be consumed by other developers, in this case the consumers are not likely to read through your code, but they might check the documentation comments, below is the example of documentation comment from the Regex namespace of .Net. 

2)      To explain why a particular approach is chosen, not to explain what a line or block of code does.

3)      If it is really hard to write self-explanatory code

In this case I would recommend, give it a try again, we have a creative brain, we always find solution. Failed again? Try again… still no luck? Okay go ahead with writing the comment, but don’t just give up, strive to refactor the code so that you could minimize the damage.

4)      To explain if you have implemented your own Algorithm, in this case you should have class level documentation comment. 

Avoid Comments in below scenarios

1)      Inline code comments : 

These are the comments should be avoided at any cost, they create noise in the code, it gets very difficult to read through the code. If you feel the comment is necessary, you should better put the block of code inside a function with meaningful name.

2)      Redundant comment: these are the comments which are absolutely useless, take a look at below code snippet. I think we all agree that the code is already clean enough to understand, we don’t require such comments. 

 Below are some points which can help you avoid comments:

1)      Do not name you classes and function randomly, the intent of class/function should be clear by just reading its name

2)      Always use descriptive variable names.

3)      Always try to follow a consistent programming model, take help of design patterns, it is a universal language for the developers.

4)      If it gets difficult to avoid comments, split your code in to meaningful modules/functions. Check if that helps.

Bottom Line:
A Programmer who is capable of solving a complex problem with simple and self-explanatory code is far better than a programmer who writes complex code and then keeps adding comments to explain it to others. Explaining yourself is good, not needing to do so is better.