Программирование без комментариев

Автор: Джефф Атвуд Источник: Codding Horror

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

'*************************************************
' Имя: CopyString
'
' Назначение: Эта подпрограмма копирует строку из исходной
' строки (source) в целевую строку (target).
'
' Алгоритм: Получает длину «source» и затем посимвольно копирует,
' каждый символ по одному в «target». Использует
' индекс цикла как индекс массива в «source»
' и «target», увеличивая индекс после копирования каждого символа.
'
' Входные данные: input — строка для копирования
'
' Выходные данные: output — строка, в которую будет скопировано содержимое «input»
'
' Предположения об интерфейсе: Отсутствуют
'
' История изменений: Отсутствует
'
' Автор: Дуайт К. Кодер
' Дата создания: 10/1/04
' Телефон: (555) 222-2255
' ИНН: 111-22-3333
' Цвет глаз: Зелёный
' Девичья фамилия: Нет
' Группа крови: AB-
' Девичья фамилия матери: Нет
' Любимый автомобиль: Pontiac Aztek
' Персональный номер на машине: "Tek-ie"
'*************************************************

Я постоянно сталкиваюсь с комментариями от разработчиков, которые не понимают, что код уже показывает, как он работает; а вот почему он работает именно так — нам нужно объяснение. Комментарии к коду так часто неправильно понимаются и используются некорректно, что можно начать задумываться, стоит ли вообще их использовать. Но будьте осторожны в своих желаниях. Вот пример кода, где вообще нет никаких комментариев:

java

r = n / 2;
while (abs(r - (n/r)) > t) {
    r = 0.5 * (r + (n/r));
}
System.out.println("r = " + r);

Понимаете, что делает этот кусок кода? Он идеально читаем, но черт возьми, что он делает?

Добавим комментарий:

java

// Вычисление квадратного корня методом Ньютона-Рафсона
r = n / 2;
while (abs(r - (n/r)) > t) {
    r = 0.5 * (r + (n/r));
}
System.out.println("r = " + r);

Теперь стало понятнее, правда? Это, кажется, золотая середина между двумя крайностями: полным отсутствием комментариев и эпическими поэмами каждые две строчки кода?

Не совсем. Вместо того чтобы добавлять комментарий, я бы просто рефакторил код так:

java

private double SquareRootApproximation(n) {
    r = n / 2;
    while (abs(r - (n/r)) > t) {
        r = 0.5 * (r + (n/r));
    }
    return r;
}

System.out.println("r = " + SquareRootApproximation(r));

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

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

Когда вы перепишете, рефакторите и перестроите свой код десятки раз ради удобочитаемости для других разработчиков — когда вы уже не сможете представить себе способа сделать ваш код ещё более простым и очевидным — только тогда, и только тогда, можно позволить себе написать комментарий, объясняющий, что делает ваш код.

Как отметил Стив, это одна из ключевых разниц между младшими и старшими разработчиками:

Раньше, если мне попадался слишком сложный или громоздкий код, я обычно пытался его переписать или хотя бы плотно закомментировать. Сейчас же я просто разбираю его без лишних жалоб. Когда у меня есть конкретная задача и сложный кусок кода, я трачу время на реализацию, а не на рассказы о ней [в виде комментариев].

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

Возможно, в этом и состоит маленькая грязная тайна комментариев: чтобы писать хорошие комментарии, нужно быть хорошим писателем. Комментарии — это не код для машины, это слова, предназначенные для людей. Хотя я, конечно, люблю своих коллег-программистов, не могу сказать, что эффективное общение с другими людьми — это наше сильное. Я видел трёхабзацные электронные письма от разработчиков, которые буквально расплавляли мой мозг. И этим людям мы доверяем писать понятные и логичные комментарии в нашем коде? Возможно, некоторым из нас лучше сосредоточиться на том, в чём мы действительно хороши — то есть писать код для машины самым понятным образом, какой только можем придумать, а комментарии использовать лишь как последнее средство.

Писать хорошие, осмысленные комментарии сложно. Это искусство не меньше, чем само программирование, а может быть, даже больше. Как сказал Сэмми Ларби в статье Common Excuses Used To Comment Code, если вам кажется, что ваш код слишком сложен для понимания без комментариев — значит, скорее всего, ваш код просто плох. Перепишите его до тех пор, пока комментарии не станут ненужными. А если после всех усилий вы всё ещё чувствуете, что комментарии необходимы — тогда, конечно, добавьте их… аккуратно и с умом.

Программирование без комментариев ​

Программирование без комментариев