О комментариях

"Не стоит относиться к комментариям как к "абсолютному добру". На самом деле, комментарии в лучшем случае являются неизбежным злом. Если бы языки программирования были достаточно выразительными или если бы мы умели искусно пользоваться этими языками для выражения своих намерений, то потребность в комментариях резко снизилась бы, а может быть и вовсе сошла "на нет".
Роберт Мартин "Чистый код"

"Комментарии должны сообщать о коде что-то такое, что он не может сообщить он сам – в виде заключения или в виде намерений".
Стив Макконнелл "Совершенный код"

Существует две крайности в отношении комментариев. Одни считают комментарии необходимым условием хорошего кода, другие считают комментарии разновидностью "запаха" (code smell) и считают, что необходимость в комментарии должна устраняться путем переписывания кода.

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

И вот, почему.

Логичность решения сильно зависит от того, понимаете ли вы контекст и ограничения, при которых это решение принималось! Одно и тоже решение может быть абсолютно глупым и абсолютно логичным, в зависимости от того, понимаете ли вы цели и намерения автора кода или нет.

Любая задача имеет множество решений, и сам код едва ли будет лучшим источником для понимания того, почему выбрано одно решение, а не другое; в таких случаях, комментарии все равно будут необходимыми.

Как? Что? Почему?

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

Использование любых "нестандартных" коллекций или алгоритмов требует пояснения. Разумно объяснить, почему используется LinkedList вместо List или SortedList вместо Dictionary. Вероятно, в первом случае, мы собираемся добавлять элементы в середину коллекции, а во втором случае мы определили, что логарифмическая сложность бинарного дерева дает более высокую производительность, по сравнению с константной сложностью хеш-таблицы.

Вы вполне можете использовать более медленный Insertion Sort, вместо Merge Sort, если знаете, что в большинстве случаев входная последовательность будет отсортированной. Добавив комментарий, проясняющий ваше предположение, ваше решение будет логичным, а без пояснения ваши коллеги рано или поздно все сломают, перейдя на более "эффективное" решение, но неподходящее для этого случая.

Очень хорошо проверить достаточность комментариев с помощью code review: если вашему коллеге не очевидно ваше решение, значит комментариев не хватает. Очень часто бывает, что во время обсуждения решения ваш коллега подчеркивает определенные моменты:

Автор кода: - Вот здесь я использую ленивое вычисление на основе yield return, а вот тут вызываю ToList внутри блока try/catch. Поскольку ToList триггерит исполнение всего LINQ запроса, то именно здесь нужно обрабатывать FormatException, с которым может упасть метод Parse, вызываемый в запросе.

Ревьюер: - Ок, но раз это так важно, то почему бы не описать эту “важность” в виде пары комментариев? А то ведь твой коллега, не понимая этой важности легко сможет вынести обработку ошибок в строку формирования запроса, поломав всю существующую логику!

Комментарии должны объяснять намерения программиста на более высоком уровне абстракции, чем код и прояснять причины текущего решения!

Вот пара простых советов по поводу комментариев:

• Комментарий не должен говорить, как мы решаем задачу. Вместо этого лучше сделать сам код более ясным.
• Комментарий может прояснять "что мы делаем" на более высоком уровне абстракции (*).
• Хороший комментарий говорит, не просто что мы делаем, а поясняет почему мы делаем именно так.
• Если что-то важно в вашем коде, то сделайте эту важность максимально очевидной! Лучше с помощью самого кода, на крайний случай – с помощью комментариев.

(*) В большинстве случаев мы можем избавиться от такого комментария путем использования более декларативного кода. Но даже хорошо структурированный LINQ запрос бывает лучше прояснить с помощью одного-двух "высокоуровневых" комментариев.

В следующий раз, рассмотрим простой пример эволюции кода и комментариев.