There are surprisingly many passionate debates going on in the developer community about the usefulness or desirability of comments in the source code. Should the code include significant comments or not contain them at all, or something in between?
Comments are defined as those lines of text that are added to the source code after a marker of a certain language to indicate non-functional text that is explicitly ignored by the compiler or interpreter.
Purpose of comments
One of the reasons why developers write comments to their code: they reflect the intent.
Any comment should describe what the developer intends to do as the goal or result of the code section. But despite this, comments should never repeat the functionality of the code.
Against comments
Some developers strongly advocate commenting as little as possible or not at all. One of the main arguments is the saying: "Good code is self–documenting." It is based on the fact that commented code is often more difficult to understand than code without comments. But there are still a number of reasons why developers refuse to comment:
Time. Comments take a long time, as does their support. Developers prefer to spend time not explaining their code, but writing it.
Incongruity. Over time, comments can inadvertently lie, which can lead to incorrect interpretation of the code.
Length. Comments make the file longer and can often make unnecessary clutter, which takes more time to read.
Code repetition. Comments often try to explain "what and how", which tends to just repeat the code. Comments should always indicate "why".
Concreteness. . It is difficult to write clear, not cryptic comments, and even more so to interpret them. If the code was written in a confusing way, then probably the comment will be the same.
Incoherence.Sometimes comments are written by developers who misunderstand the code, and reinforce this misunderstanding with incorrect or misleading text.
For comments
Intentional commenting has advantages despite disadvantages. First of all, comments help the person who wrote them. The next reason, but not the least, is that they can make it easier for others to understand.
The time to read and understand the code is reduced
Since with the help of comments you know what is going to happen, this gives you a basis for interpreting this section of code. This can be especially useful if you are trying to get back on track after a break.
Finding a specific functional section of the code becomes easier
It will be easier to find some specific code in a large unfamiliar project if it contains comments. Without them, you will have to view hundreds and thousands of files and spend time reading them. The search tools only help if you can guess the function name. Intentional comments give you a foothold.
You can reconstruct the developer's thinking patterns
A relevant comment with intent answers the question: "What was the previous developer going to do here?".
The discrepancy between the commented intent and the actual result of the code indicates potential errors
The error is easier to detect if the code contains a comment about intentions. For example, the developer intended to do one thing, and the code did not correspond to these intentions.
Non-programmers can also participate
The manager, client, designer, open source user, etc. will also be able to view your comments and better understand what is happening. Since comments about intentions are language-independent, they provide a basis for useful feedback.
The code automatically becomes a tutorial
Interns can read certain sections of the code with comments if they don't understand something. This will allow them to learn even advanced and complex patterns and algorithms.
The discussion about comments in code is not new. There are strong arguments for and against them. Yes, commenting costs the developer time when writing, but saves others time when understanding the code at a later stage. The main thing is to add meaningful comments to improve the readability of the code.