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

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

Ответ

Хороший комментарий — ненаписанный комментарий. Следует стремиться писать код так, чтобы комментарии были просто не нужны.
Проблема комментариев в том, что
часто они находятся в одном месте, а помнить о них их нужно в другом компилятор не может проверить истинность комментария, поэтому при изменении кода комментарий устаревает
Пройдёмся по часто встречающимся случаям, в которых комментарии излишни.
Если вы хотите прокомментировать, для чего нужна какая-то переменная, выбросьте комментарий, и измените имя переменной на более подходящее.
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; }
(а если бессмысленные комментарии требуются от вас стандартами кодирования, потребуйте изменения этих стандартов!)
Таким образом, что происходит в участке кода, должно быть по возможности понятно из самого куска кода. Если это не так — улучшайте его.
Если комментарий представляет собой на деле документацию к вашему коду, тут ничего не поделаешь, удалять его не нужно.

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