Почему комментарии в коде — зло

Обратная сторона правильного тона.
03 октября 2017326451Илья Бубнов3203518

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

Кому и зачем нужны комментарии

Комментарии в коде несут четыре функции:

  1. Улучшают навигацию. В случае возникновения ошибки или необходимости доработать какой-то момент в программе, вы или любой другой разработчик быстро найдёте соответствие ему в коде.
  2. Объясняют написанное. Полезно при использовании математических, физических, экономических формул, которые рядовому программисту непонятны или неизвестны.
  3. Описывают код в общем. Это бывает полезно при создании библиотек, работе с системными переменными, да и вообще в любых случаях создания общедоступного кода.
  4. Описывают результаты. Это когда разработчик не объясняет написанное, а использует комментарии для отладки и проверки себя.

Чем плохо

В 2008 году на полках книжных магазинов впервые появилось произведение Роберта Мартина «Чистый код». В ней автор описал множество способов по оптимизации кода, одним из которых является практически полный отказ от комментариев. Они, по мнению Мартина, в большинстве случаев указывают на неспособность разработчика грамотно выразить свои идеи в переменных и функциях. Комментарии помогают не тратить много времени на обдумывание структуры кода, имен, не заботится об удобочитаемости.

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

Что делать

Сразу оговоримся: комментарии — неотъемлемая часть кода. Но они не должны пояснять код, они должны помогать его читать.

Таким образом, в качестве первого упражнения будет полный отказ от однострочных подписей справа от кода. Не просто удалите их, а сохраните информативность и читаемость программы. Многострочные комментарии по-прежнему можно использовать, они будут выполнять роль путевых заметок. Данный способ поможет вам:

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

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

Простой пример: при заполнении анкетной формы переход к следующему разделу происходит только если все поля заполнены верно. Если где-то допущены ошибки, то это место выделяется красным цветом. Способ отразить это в коде — использование флагов. Из моего опыта они часто носят имена вида:

flag_2;

validatedSurname;

surnameField;

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

if (validatedSurname! = null)

Вам потребуется прочитать следующую строчку, вернуться на пару абзацев выше, чтобы удостовериться — да, это флаг заполнения поля. Ещё раз, это допустимая запись для небольшого кода, где у вас минимум текста, 5−6 полей. Но если код занимает десятки листов и в нём есть несколько имён с приставкой «Surname», стоит обозначить данный флаг более явно и конкретно.

Второе упражнение — переписывание кода с максимально возможным использованием наследования и инкапсуляции. Даже если вы пишите не на языке ООП, подобную архитектуру можно создать, просто манипулируя именами. К примеру, FormSurname, FormSurnameField, FormSurnameFieldFilled, FormSurnameFieldCorrectlyFilled и так далее. Полученный код будет трудно назвать удобочитаемым, однако это прекрасная тренировка метода необходимости и достаточности.

И всё же без комментариев никуда

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