Clean Code Thoughts — Comments

It is time to talk about code comments. I think they can be basically three things: good, bad and funny (especially when you don’t have to deal with it). Now, let’s think about “Which kind of problems comments are trying to solve?”.
- We can change software behavior quickly and test it, even in production. (and we can forget that “feature” there).
- We can make jokes to colleagues.
- We can write TODOs.
- We can write software license in the code.
- Ok! We are able to provide some information to another developer. Usually, this information is needed because we are not always able to express ourselves without them. Why? Sometimes due to the programming language, the dubious nature of the problem or even our language, lack of knowledge and I am pretty sure we can grow this list easily.
When Comments could be a GOOD idea
Legal Comments
There is not to much to say about it. It is legal and we have to write it. Configure templates on your IDE to do it for you.
Explanation of intent or clarification
Sometimes you need can feel it is necessary explain what you tried to do due to some complex algorithm or another any reason. However, be sure you are not able to improve the code design.
Warning consequences and Amplification
There are moments you’ll need to express the importance regarding the code. In both cases you’re saying: “Hey! Pay attention here, think twice before doing anything”.
An example worth more than 1000 words. :)
//
// 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 = 42
//
TODO comments
My recommendation is never write a TODO! If you realize you need to do something, just do it. If you can’t do it right now, please, create a ticket and put it in somewhere visible. Otherwise, there is a good chance that TODO be forgotten.
JavaDocs and Public APIS
Think about Javadoc or public APIs, I can’t live without them! If you’re developing some API or library it is necessary to write a good documentation for your clients.
When Comments could be a BAD idea
There are a huge amount of bad comments out there. Thefore, I am going to focus on the most important ones, considering my point of view.
Redundant
When just by reading the code you’re able to understand what is going on. In other words, when you have self explained, adding comments is redundant.
Misleading
When the comment is supposed to help but it is only adding misleading information; it can happen when you change a method, for example, adding or removing behaviors and you forget to update the comment.
When you can use a function or a variable
Always try to give meaningful names to variables and you won’t feel the need to explain the code using comments.
Commented Code
Please, don’t leave commented code out there! People will be afraid to remove it. I believe you are using a version control system. So, just remove this commented code.
Relevant points about comments
- It is not about don’t write comments at all. It is about spending energy to write self explanatory code instead of writing comments that are unhelpful;
- Programmers are not always used to maintain comments;
- Programmers are trained to skip useless comments;
- Rules that compel programmers to document everything (methods, variables etc) will encourage them to write bad comments as well as ignore most of comments.
- Usually, comments can become inaccurate and useless;
- The code can be self explanatory removing the need to insert more information than necessary;
- As software developers, we are writers. Therefore, it is important to improve our code writing ability in order to do it more expressively.
- If you can’t be clear writing code you probably won’t write clean comments as well;
- If the code is not well written, instead of try to explain it in comments, put your energy refactoring it;
- Public APIs should have documentation. Therefore, make a good use of comments in order to write it clear.
Conclusion
At first sight, comments seemed to be a trivial subject to write about it but it is not true when you start to go deeper. It is important to keep yourself disciplined while writing code as well as building good SOLID, refactoring and unit testing knowledge. I am convinced that these three areas will lead you through clean code.
Last but not least, take a look to these comments! :)

