How to correctly comment on the code

Once I sat in the audience with a laptop near the outlet, but at that time a programming test was taking place at a nearby desk. I didn’t really get into the essence of the questions that the student and teacher talked about, let's call him Ivan Ivanovich. The conversation was rather calm and quiet, but I managed to grab a part. The teacher spoke about the comments (apparently gave up the program, in which there was not a line of comments). I was interested in this moment and I began to listen. It was noticed that I was also interested, the teacher began an improvised lecture. Below is the small piece of knowledge that I then learned from this 5 minute lecture.



I would like to immediately warn you that for many the things described here are obvious things, however, for beginners in collective programming (when 2 or more programmers are working on the code) and it will be useful for students. In addition, all of the following tips have an alternative and can be used only partially.



Why did I assign students here? They, it would seem, some work on the program to offset! When he accepts the program, the lecturer is rightly considered the second developer, who ideally without the help of the student should understand what is written there and how it works.

How to write code immediately with comments

')

Essentially speaking, in that lecture, the principle of TDD (Test-driven development, development through testing) was moved to a lower level. I do not remember how it sounded in the original, but in fact “Describe the structure of the code with comments” . On the example of (highly exaggerated, why - below) program code that adds two numbers, this principle will look like this:

int main() { //      //      //    return 0; } 

And only when the skeleton of comments is ready, you should write code that will implement what is described by comments.

 ... int main() { double a,b; //      cin>>a; cin>>b; //     double sum = a+b; //    cout<<sum; return 0; } 

As mentioned above, this principle is a modified principle, well-proven TDD. Here it should be understood that deviating from comments, unlike deviations from the logic of tests, will not lead to serious consequences, well, unless you have to rewrite comments



Now let us imagine a “purely hypothetical” situation, when there is already a code of 200,000 lines, written by a brilliant programmer, a crooked Indian, and does not contain a single line of comment. However, you need not only to kill this programmer to understand this code, but also to accompany it in the future. You even understood this code, and being a decent person, you decided to supplement the code with comments for future generations, so to speak. But the question arises: how?

How to comment on already existing code

The answer to this question is quite simple: we comment on entities from parent to child: class -> method -> code inside the method (if necessary).



It would be logical to think: what does not need to comment. It is not necessary to comment in two cases (one of them explains why the code sample above was highly exaggerated):

• Very obvious things. Comments of the form // we initialize the counter enrage more than their absence
• Incomprehensible code add comment type // did not understand

Regarding the second point, it is worth explaining a little and give an example: insert 100 lines of assembler code in C! You look at her and write a comment // Many books! Niasilil

After that, the person who came to your place after your dismissal sees this comment and ... everything! He will not even try to figure it out and this entry will be a stigma on this piece of code until it is removed (either a code or a comment).

At last

In conclusion, I can say that the art of writing comments is an integral part of the art of programming, so comments need to be written , and, as pathetic as it sounds, but you need to learn how to write high-quality comments.