День девятьсот четвёртый. #BestPractices
Лучшие Практики Написания Комментариев к Коду. Начало
Знаменитый профессор MIT Хэл Абельсон сказал: «Программы должны писаться для того, чтобы быть прочитанными людьми и лишь на всякий случай - для выполнения машинами». Хотя он, возможно, намеренно недооценил важность исполнения кода, он чётко понимает, что у программ есть две очень разные аудитории. Компиляторы и интерпретаторы игнорируют комментарии и считают, что все синтаксически правильные программы одинаково просты для понимания. Читатели-люди сильно от них отличаются. Нам кажется, что одни программы труднее понять, чем другие, и мы ищем комментарии, которые помогут нам разобраться в них.

Существует множество ресурсов, помогающих программистам писать код лучше, вроде книг или статических анализаторов, но мало ресурсов для написания хороших комментариев. Количество комментариев в программе измерить легко, трудно измерить их качество, и эти два понятия не обязательно коррелируют. Написание и последующее поддержание комментариев - это расходы. Компилятор не проверяет ваши комментарии, поэтому невозможно определить их правильность. С другой стороны, он гарантирует, что компьютер делает именно то, что ему говорит ваш код. А плохой комментарий хуже, чем его отсутствие. Но было бы ошибкой впасть в другую крайность и никогда не писать комментарии. Вот несколько правил, которые помогут вам достичь золотой середины.

1. Комментарии не должны дублировать код
Многие начинающие программисты пишут слишком много комментариев, потому что их научили этому в школе. Кого-то учили добавлять комментарий к каждой закрытой скобке, чтобы указать, какой блок заканчивается:

if (x > 3) {
  …
} // if

Некоторые преподаватели требовали от студентов комментировать каждую строчку кода. Хотя это может быть разумной политикой для совсем уж новичков, но такие комментарии похожи на ходунки для младенцев, и их следует удалять, как только вы научились ходить.

Комментарии, которые не добавляют информации, имеют отрицательную ценность, потому что они:
- добавляют визуального беспорядка,
- требуют времени на написание и чтение,
- могут устаревать.

Канонический плохой пример:

i = i + 1; // Добавляем 1 к i

Комментарий не несёт никакой информации, но повышает стоимость поддержки кода.

2. Хорошие комментарии не оправдывают непонятный код.
Ещё одно неправильное использование комментариев - предоставление информации, которая должна быть в коде. Простой пример - когда кто-то называет переменную одной буквой, а затем добавляет комментарий, описывающий ее назначение:

private static Node getBestChildNode(Node node) {
  Node n; //кандидат на лучшего потомка
  foreach (Node node in node.getChildren()) {
    //обновляем n, если текущий лучше
    if (n == null || utility(node) > utility(n))
      n = node;
  }
  return n;
} 

Необходимость в комментариях отпадает, если лучше обозвать переменные:

…
Node bestNode;
foreach (Node currentNode in node.getChildren()) {
  …
}

Не комментируйте плохой код, просто перепишите его.

Продолжение следует…

Источник: https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/