Почему комментарии в коде — зло
У хорошего кода есть несколько признаков: правильные имена, простые решения, смысловое разделение на блоки, структурированность, комментарии разработчика. Однако последний пункт — далеко не всегда признак профессионала. Иногда это проблема новичка, мешающая перейти на следующий уровень мастерства. Постараюсь объяснить почему.
Кому и зачем нужны комментарии
Комментарии в коде несут четыре функции:
- Улучшают навигацию. В случае возникновения ошибки или необходимости доработать какой-то момент в программе, вы или любой другой разработчик быстро найдёте соответствие ему в коде.
- Объясняют написанное. Полезно при использовании математических, физических, экономических формул, которые рядовому программисту непонятны или неизвестны.
- Описывают код в общем. Это бывает полезно при создании библиотек, работе с системными переменными, да и вообще в любых случаях создания общедоступного кода.
- Описывают результаты. Это когда разработчик не объясняет написанное, а использует комментарии для отладки и проверки себя.
Чем плохо
В 2008 году на полках книжных магазинов впервые появилось произведение Роберта Мартина «Чистый код». В ней автор описал множество способов по оптимизации кода, одним из которых является практически полный отказ от комментариев. Они, по мнению Мартина, в большинстве случаев указывают на неспособность разработчика грамотно выразить свои идеи в переменных и функциях. Комментарии помогают не тратить много времени на обдумывание структуры кода, имен, не заботится об удобочитаемости.
Простой пример: если рядом с каждой функцией уточняется, какое действие зачем выполняется — данные комментарии написаны либо от скуки, либо из-за незнания правил хорошего кода.
Что делать
Сразу оговоримся: комментарии — неотъемлемая часть кода. Но они не должны пояснять код, они должны помогать его читать.
Таким образом, в качестве первого упражнения будет полный отказ от однострочных подписей справа от кода. Не просто удалите их, а сохраните информативность и читаемость программы. Многострочные комментарии по-прежнему можно использовать, они будут выполнять роль путевых заметок. Данный способ поможет вам:
- оценить качество и понятность кода;
- обратить внимание на большое количество ненужных комментариев;
- найти пути оптимизации, упрощения и улучшения кода;
- научиться правильному оформлению — пробелы, табуляции, отступы.
Когда у вас нет возможности комментировать всё, что находится слева, вы как минимум постараетесь передать смысл в названиях переменных и функций.
Простой пример: при заполнении анкетной формы переход к следующему разделу происходит только если все поля заполнены верно. Если где-то допущены ошибки, то это место выделяется красным цветом. Способ отразить это в коде — использование флагов. Из моего опыта они часто носят имена вида:
flag_2;
validatedSurname;
surnameField;
Первый вариант типичен для проектов совсем юных гиков, но не имеет права существовать в профессиональном варианте даже с обильным комментированием. Два других — допустимы, но вырванная из контекста строчка может не давать мгновенного ответа, что происходит:
if (validatedSurname! = null)
Вам потребуется прочитать следующую строчку, вернуться на пару абзацев выше, чтобы удостовериться — да, это флаг заполнения поля. Ещё раз, это допустимая запись для небольшого кода, где у вас минимум текста, 5−6 полей. Но если код занимает десятки листов и в нём есть несколько имён с приставкой «Surname», стоит обозначить данный флаг более явно и конкретно.
Второе упражнение — переписывание кода с максимально возможным использованием наследования и инкапсуляции. Даже если вы пишите не на языке ООП, подобную архитектуру можно создать, просто манипулируя именами. К примеру, FormSurname, FormSurnameField, FormSurnameFieldFilled, FormSurnameFieldCorrectlyFilled и так далее. Полученный код будет трудно назвать удобочитаемым, однако это прекрасная тренировка метода необходимости и достаточности.
И всё же без комментариев никуда
Комментарии, наложенные на хороший код — абсолютное благо. Они улучшают навигацию, позволяют понимать, что ожидал разработчик получить по исполнению того или иного блока. Злом они являются только в наиболее распространенном случае — объяснение написанного. Такие комментарии являются костылями, которые создают видимость грамотного кода. Отбросьте эти костыли, и вы пойдёте к вершинам профессии куда быстрее.