So why do we comment our code? To give a better explanation about a code we have written. But why do we have to explain a code we have written as code are meant to be self-explanatory. So if you are adding comments to your code, does it mean that your code was not self-explanatory? If your code was not self-explanatory, do not bother adding comments to the code, kindly refactor your code. What is the essence of commenting a bad code?
A lot of programmers want to give better clarification about what they are doing and as such, employ every means possible to achieve that. However, following some basic naming principles, we would not have to comment our code. But be careful, I do not say you do not need to comment at all. There are cases in which comments are a must, but where they are not necessary, they are a source of nuisance and space misappropriation.
Unlike codes, comments are rarely refactored. Most of the time, it is rather difficult to refactor comments after they have been written. Be careful, because a bad comment is far worse than no comment at all. It misleads, it lies, it causes a very great level of inaccuracy when reading the code. Try as much as possible to explain yourself in your code and far away from comments.
Beyond stating the bad sides of comments, listed below are some of the places where comments can serve good purposes, but even in those places its use should be limited
- Legal Rules: This is where the copyright law for the code and the organization and the authors of the code are written. Since this type of comment can be found in almost every file, it would rather be important if it can be written in a separate file for the project
- Informative Comments: No matter how descriptive our namings are, we sometimes need some helper comments to shed more light on certain names. In these cases, use comments. but be careful as these cases are really rare. Always explain yourself in code
- Intent: Some implementations need to be followed by the intent why the programmer chose to use some certain concepts to solve the problem. In this case, comments can be used to explain intent.
- Warning: Some implementations can use more resources than needed at some certain time or do something we do not want all the time. A certain method execution might drop all the data in the database. For these rare cases, comments can be added to warn anyone before they try using a certain method
- Todo: Not all tasks can be completed at once. Comments can be added to explain that certain code is still in progress or another programmer looking at the code should complete some other items in progress.
- Emphasis: To lay more emphasis on a certain piece of code. Comments can be added to give the developer a heads-up.
There could be more reasons why you want to add comments to your code but the reasons stated above are some that scaled through the acceptable comments bar. Beyond acceptable comments, what comments are bad? Check it out in Part 2 of this article