What should the comment say in the code?

A good comment is an unwritten comment. You should strive to write code so that comments are simply not needed.

The problem with comments is that

• Often they are in one place, and remember them they need them in another
• the compiler cannot verify the truth of the comment, therefore the comment becomes outdated when the code changes

Let's go through the frequent cases in which comments are unnecessary.

1. If you want to comment on what a variable is for, throw out a comment and change the name of the variable to a more appropriate one.

   int n; // количество страусов 

   better to replace

    int numberOfOstriches; 

2. If you want to report that some condition is met, it is better to put an assert :

    // тут pBFG не может быть nullptr-ом, проверка не нужна pBFG->fire(); 

   better to replace

    assert(pBFG); pBFG->fire(); 

3. If you describe in a comment what exactly a piece of code does, it makes sense instead to allocate this piece as a separate function , and make the meaning of the code its name.

    // нормализовать вектор скорости double temp_length = sqrt(velocity.x * velocity.x + velocity.y * velocity.y); velocity.x /= temp_length; velocity.y /= temp_length; 

   better to replace

    void Normalize(vector& v) { double length = sqrt(vx * vx + vy * vy); if (length == 0.0) throw argument_exception("zero length vector"); vx /= length; vy /= length; } 

    Normalize(velocity); 

4. If you describe self-evident things in a commentary, it’s better to just throw out this comment.

    // этот класс представляет точку class Point { public int X; // координата X public int Y; // координата Y } 

   not a bit lost in readability in this form:

    class Point { public int X; public int Y; } 

   (and if meaningless comments are required of you by coding standards, ask for changes to these standards!)

Thus, what happens in a section of code should be as clear as possible from the piece of code itself. If not, improve it.

If the comment is in fact the documentation for your code, there's nothing you can do, you do not need to delete it.

Those few places where comments are really needed are descriptions of the algorithms used, optimizations, documentation of bug fixes and non-obvious solutions. Here again, try to write about why you are doing what you are doing. And how exactly you are doing should be clear from the code.