О чем должен говорить комментарий в коде?

#любой_язык #code_style

О чем должен говорить комментарий в коде? О том, что происходит в следующем блоке
кода или о том, что должно произойти в результате выполнения этого блока кода? Что
в этом вопросе подсказывает/требует практика?
    

Ответы

Ответ 1

Хороший комментарий — ненаписанный комментарий. Следует стремиться писать код так,
чтобы комментарии были просто не нужны.

Проблема комментариев в том, что 


часто они находятся в одном месте, а помнить о них их нужно в другом
компилятор не может проверить истинность комментария, поэтому при изменении кода
комментарий устаревает


Пройдёмся по часто встречающимся случаям, в которых комментарии излишни.


Если вы хотите прокомментировать, для чего нужна какая-то переменная, выбросьте комментарий,
и измените имя переменной на более подходящее.

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


лучше заменить на

int numberOfOstriches;

Если вы хотите сообщить, что выполняется какое-то условие, лучше поставить assert:

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


лучше заменить на

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

Если вы описываете в комментарии, что именно делает кусок кода, имеет смысл вместо
этого выделить этот кусок в отдельную функцию, а смысл кода сделать её именем.

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


лучше заменить на

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




Normalize(velocity);

Если вы описываете в комментарии самоочевидные вещи, лучше этот комментарий просто
выкинуть.

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


ни капли не теряет в читаемости в таком виде:

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


(а если бессмысленные комментарии требуются от вас стандартами кодирования, потребуйте
изменения этих стандартов!)


Таким образом, что происходит в участке кода, должно быть по возможности понятно
из самого куска кода. Если это не так — улучшайте его.

Если комментарий представляет собой на деле документацию к вашему коду, тут ничего
не поделаешь, удалять его не нужно.



Те немногие места, где комментарии действительно нужны — описания используемых алгоритмов,
оптимизаций, документация багфиксов и неочевидных решений. Здесь снова-таки старайтесь
писать о том, почему вы делаете так, как делаете. А как именно вы делаете, должно быть
понятно из кода.


Ответ 2

"Ну ты, барин, и задачи ставишь"... (с) К/ф "Формула любви"

К комментариям нет требований. Понимаете, это все равно как спросить - рассказ должен
описывать намерения автора или действия персонажей? Сама постановка странная - что
именно писать в комментарии... А уж различать "что происходит" и "что должно произойти"
- это уж совсем странно.

Вообще-то код нужно писать так, чтоб он сам по себе комментировал, что он делает.
Придумано не мной, но я с этим, в общем-то, согласен. И уж точно не нужно комментировать
в духе "присваиваем переменной сумму двух других" :)

Пишите комментарии так, чтобы вы через год-два могли глянуть на код и разобраться,
что же он делает.

Отдельно я бы выделил комментарии о том, что надо не забыть сделать :)

Если работаете в команде - то работайте так, как решено командой. 

Под конец процитирую Саттера:

Не предписывайте стиль комментариев (кроме тех случаев, когда специальный инструментарий
использует их для документирования), но пишите только нужные и полезные комментарии.
Вместо комментариев пишите, где это возможно, код.


Ответ 3

Хорошие комментарии именно  в коде (а не перед функциями и т.п.)  должны пояснять
зачем этот кусок нужен для решения задачи.

Вполне вероятно, что для понимания этого "зачем", потребуется описать состояние исходных
данных и что получается после выполнения комментируемого кода. 

А как именно это реализуется, желательно рассказывать самим кодом.