Why [don't] need to comment on the code

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

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

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

    Or the more radical “ Comments are the first sign of bad code .”
    In principle, the idea is correct, the code should be clean. A clean code does not need comments; it is understandable anyway. If you have a desire to explain by means of a comment what this variable means - can it be better to rename it so that it becomes clear from the name? If it seems to you that the algorithm of the method is a bit confusing, 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 quality refactoring, and just write as you can. Sometimes the business logic itself is so confused that without 100 grams it can not be implemented. And when you realize it, you want to forget about this task and, just in case, take a shower, about five times. And sometimes, what seems beautiful and logical to you can cause difficulties for your colleagues.

    So can code itself be the best documentation? Of course it can, but to be 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, this will save someone a little time.

    Statement 2: “Comments may be outdated.”

    This means 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 indiscretion, forgot to correct the comments. And after half a year, your other colleague lost a lot of time, because he was misled by irrelevant comments.
    The problem is not far-fetched, I, for example, have repeatedly met comments that do not correspond to the code ... but what's there ... I myself used to forget to rewrite the comments. There is a problem, but I do not think that excluding comments at all is the best solution. You just have to be careful, and don't forget to correct the comments when correcting the code.


    Do not get me wrong, I am not campaigning for commenting on every line. Moreover, I myself consider comments in the style of:
    $i++; // Увеличиваем счетчик

    sign of bad code. Comments must not duplicate code! They must complement it!

    I like the comments to answer the question “ Why ?” Rather than “How?”. Such comments would really save me time more than once. It happens that you look at someone else's code, and in your head the thought “Why is that? You can do it easier! ”, And after half an hour you realize that yes, that’s right. It’s easier than that. When programming, we often stumble upon various pitfalls that affect our code in one way or another. If you choose not the most obvious and simplest solution - do not be too lazy to describe why you did this.


    As always, both opinions have a right to exist. If mine is interesting: “The code that may cause embarrassment needs comment.” If someone assures that the comments are evil, I will not argue, but I will remain in my opinion. Most importantly, if you decide to refuse to comment, make sure that the reason is in an understandable and logical code, and not in banal laziness .

    Also popular now: