Неужели комментировать код — это плохо?

Что такое комментарий?

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

Какой в нем смысл?

Как правило, «прочесть» код достаточно трудно. А поясняющий текст помогает разработчикам «объяснить» написанное тому, кто займется поддержкой кода в дальнейшем.

Нужны доказательства? Возьмем вот этот код без комментариев:

let o_fac = new BGF()
let bg_a = o_fac.build("ALIEN");
bg_a.i_health(100);
bg_a.i_armor(50);
bg_a.i_attack(50);
game.v_Add(bg_a);

Этот блок кода выполняет несколько функций. Результат: программисты не могут быстро понять, что же именно делает данный код.

А теперь снабдим тот же код комментариями.

// create the alien object.
let o_fac = new BGF()
let bg_a = o_fac.build("ALIEN");

// set Alien details.
bg_a.i_health(100);
bg_a.i_armor(50);
bg_a.i_attack(50);

//add to game
game.v_Add(bg_a);

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

Мы же, разработчики, привыкли мыслить критериями «что», забывая про «как».

Так, получается, что комментарии объясняют наш код?

Да.

Звучит не плохо …

Так и есть. Но пояснять код можно разными способами. И комментирование является самым худшим из них.

Почему же комментирование стало «самым худшим»?

Причин для этого сразу несколько. Для начала, нет никакой гарантии того, что кто-то прочтет ваши комментарии. На практике, мало кто из разработчиков обращает на них внимание. Посмотрите на этот скрин Webstorm. В изначальной цветовой гамме комментарии выделяются серым и совершенно непримечательным цветом:

Так почему бы не завести блог с названием «Пожалуйста, читайте комментарии»?

Хороший вопрос! Потому что нельзя верить комментариям, которые вы читаете.

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

Как и в любой другой системе с несколькими источниками истины, разработчик может обновить один код, но забыть о другом. Можете ли вы, положа руку на сердце, сказать, что при корректировке кода вы действительно вчитываетесь во все комментарии и следите за их корректностью?

Конечно же, нет, это часто забывается.

Вот именно. Так что делайте так, чтобы в ваших системах присутствовал лишь один источник истины.

Хорошо, признаю, комментарии — это не самое правильное решение. Но ничто не идеально в этом мире. Так вы говорите, что есть вариант получше?

Да. Покажите мне ваш комментарий, и я предложу вариант получше.

А как насчет комментариев с описанием переменных? Вы говорите, что лучше не прибегать к ним для создания пояснений по переменным?

90% of all code comments: pic.twitter.com/SVzOopZxUB

— Carter Wickstrom (@carterwickstrom) July 3, 2018

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

// Bad.
let x; // Variable to hold id of car being displayed.

// Good.
let displayedCarId;

Такой принцип применим и к функциям, не так ли?

Да. Присвойте функциям и параметрам имена на основании их назначения. Как только это сделано, необходимость в комментировании стиля заголовка функции отпадет сразу.

А что насчет предыдущего кода? Там комментарии описывали блоки кода, совместно обеспечивающие его функциональность? Одно именование нам явно не поможет, разве нет?

Нет, оно как раз нам поможет. Несколько строк кода с совместным выполнением определенного действия можно вывести в правильно поименованную функцию. Взгляните сюда:

let alien = alienFactory
              .createAlien()
              .withStats({
                  health: 100,
                  armor: 50,
                  attack: 50
                })
              .getAlien();

game.add(alien);

Видите, как этот код выведен в функцию, которая описывает свое назначение? То же распространяется и на статичный код. К нему не требуется дальнейшего пояснения; код делает то, что написано.

Еще один плюс от использования функции в данном примере заключается в том, что все лишние детали скрыты. Мейнтейнеру не придется беспокоиться о том, как работают функции, не относящиеся к отдельно взятому изменению в коде. И так код становится удобнее для понимания.

Кроме того, мейнтейнер не проигнорирует имя функции, тогда как про комментарий он может и забыть. Имя функции уже является составляющей кода. Поэтому при прочтении всего кода прочтется и имя, и вызов функции.

А вдруг мне придется хорошенько потрудиться над оптимизацией какого-то кода. Можно ли тогда обратиться к комментариям?

Да.

Стоп… что?

Мы — разработчики программных продуктов. И у всех разработчиков есть инструменты. Комментарии — это те же самые инструменты, что и функции с именами переменных. Но ни одно средство не решает все проблемы сразу. И одного инструмента всегда мало. Если изменение структуры кода не улучшает его читабельность, то стоит вспомнить про комментарии.

Так комментарии — это хорошо?

Нет, комментарии — отстой! Большая часть комментариев, которые я встречал на практике, — никуда не годится. В основном, комментарии используют, чтобы извиниться за:

· неправильное именование переменных или функций.

· сложность или длину кода.

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

Перевод статьи Sam Fare: Do code comments suck?