Why [do not] need to comment on the code

Recently, the idea is gaining popularity that the comments in the code are not mandatory, and even harmful. Just last night, talking to a familiar young programmer who asked to see his code, I found that there were no comments at all, even the usual descriptions of methods. To my surprised smiley, the answer was: “ Comments are the first sign of a bad code ”. And to hell with him, with a novice programmer, but I occasionally read something similar in blogs, and hear from colleagues. Maybe programming once again took a step forward, and I, among the laggards? Under the cut, a little thought, about when and why you should or should not comment on your code.

So, there are two main statements against comments in the code:

Statement 1: “Code is my own best documentation.”

Or more radical “ Comments are the first sign of bad code ”.
In principle, the thought is correct, the code must be clean. A clean code in the comments does not need, it is already clear. If you have a desire, explain by commenting what this variable means - can it be better renamed so that it would be clear from the name? If it seems to you that the algorithm of the method is a little confused, maybe instead of writing a comment, it is worth rewriting the algorithm, making it more understandable and logical?

Unfortunately, in real life, it is not always possible to produce a beautiful and logical code. Sometimes there is not enough time for high-quality refactoring, and just write as you can. Sometimes the business logic itself is so complicated that you cannot implement it without 100 grams. And when you realize, you want to forget about this task and, just in case, take a shower, five times. And sometimes, what you think is beautiful and logical, can cause difficulties for your colleagues.
')
So can the code itself be the best documentation? Of course it can, but for sure, do not be afraid to insert an extra line of comment, or at least make a reference to the pattern used. Perhaps in the future, it will save someone a little time.

Statement 2: “Comments may become obsolete.”

It is understood that comments may at some point cease to correspond to the code. For example, you wrote a certain method in whose body you left a lot of comments, because, according to the previous paragraph, you want to save time for your colleagues. After half a year, your colleague, changed the method, but in a hurry, or out of rashness, forgot to correct the comments. And after another half a year, your other colleague lost a lot of time, because he was misled by irrelevant comments.
The problem is not contrived, for example, I have often met comments that do not correspond to the code ... but what is there ... I myself forgot to rewrite comments. There is a problem, but I do not think that eliminating comments at all is the best solution. You just need to be careful and do not forget to correct the comments when correcting the code.

Why?

Understand me correctly, I am not agitating for commenting on each line. Moreover, I myself consider comments in the style:

$i++; //  

. ! !

“?”, “?”. , . , , “ ? !”, , , . . , , . — .

.

, . : “, , ”. - , — , , . , , , , .