Do not forget that the code and comments forms a set. So we must pay due attention to both sections. For our code is elegant, clean and easy to maintain, we can follow the following tips.
Use descriptive names
It is a basic rule, although not directly related to the comments, it greatly influences them. Our variables, classes and methods should have a descriptive name.
Typically, the class names are nouns representing an entity (Customer, Supplier etc.). The methods represent an action, so that its name often contains a verb. We also try variables, properties and parameters to have a name that describes the value containing (total_clientes, total_number etc.).
What do we get with this? More the code is readable, less time it will take to review the code.
Using descriptive names, the code does not need additional comments. Any programmer who reviews the code will be able to get an idea of what the code does.
Comments must be useful
No need to explain obvious things. The source code in 98% of cases is readable by another developer, or at least someone with programming skills.
That comment does not add anything. Better if we eliminate. Better yet if we do not write it.
Think before adding comment if a review is necessary
If we have to add a review, it is better to think about it before you do. Why should I add this comment? Is it really necessary? Can I refactor my code to prevent this? Perhaps the code we have written is too complex and therefore needs to be explained. In that case, we can separate it into simpler methods. Always follow the rule to use descriptive names.
With this simple idea, we can also identify potential design errors
Avoid comments inside methods or functions
It may be helpful to discuss what makes a method before your return. We can even discuss their parameters but keep in mind that we must discuss the “what” and not the “how.” That is, we must explain what makes our method. The “how” makes the function or the logic in the method.
Do not comment out removed code
Sometimes we have to remove some of the code. And sometimes, in a fit of “just in case”, commented the code removed for safekeeping. This is something that does not make sense. You should have a control system source code for these things. And if we do not, we have more serious problems than the comments.
Comment should be concise and updated
A comment has to be clear and explain things well but the comments also must be updated. If we describe the method, and when the functionality changes, we have to update the comments. So, the comments are better to be short and concise.
Beware of misleading comments
Is something not done often on purpose but it can give us more of a headache. It has to do with the previous point and the problem of not keeping the comments. Sometimes it is because we allow ourselves to do something, or why a specification has changed, our comment will become obsolete. Or worse, the comment expresses it differently from what you are actually doing. If we trust the comment, we can generate unexpected errors.
Always follow the same style
It is always advisable to discuss the code in the same way. A definite style helps to understand the code who is reading it. If a method always comments with an introduction and a description of the parameters, we have to be consistent and do it in all methods. The person reading it may end up confused by the disparity of criteria.
Do not leave comments for the later
Generally those who develop a behavior of not writing a comment or leaving it for later. Because it’s boring, and we usually leave that for later. But procrastinating on the commented code is a bad idea for several reasons.
The first is that, in the end, we will have to discuss a large volume of code at once. That’s even more boring, and our comments will be worse. The second is that ideas lose freshness as time passes. Post code not just done is more complicated but also takes longer.
Best is comment while writing code or better comment before start coding. Writing what you have to do, you’ll have a better understanding of the problem.
Better to be polite
This depends on the scope of some source code. In work environments, we must be serious and correct especially if the code is for a client. If the code we’re doing for us, comments can have a more relaxed tone. Yes, it is best to avoid swearing because you will never know who might read the reviews.