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

Комментарии — аннотации, которые делают код более доступным и удобным для чтения и понимания.

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

Когда комментарии — хорошая идея?

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

Вот главные плюсы использования этого инструмента:

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

— Улучшение взаимоотношений. Хорошие и полезные комментарии помогают создать более дружелюбную и продуктивную атмосферу в команде.

— Эффективная отладка. Понятные комментарии сокращают время на поиск и устранение ошибок. Разработчики могут быстро понять, какие задачи стояли, и быстро локализовать проблему.

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

Типы комментариев для разных задач

Выделяют несколько типов комментариев, у каждого из них — своя роль в объяснении и документировании кода. Сгруппируем их по смыслу и рассмотрим на примерах.

Поясняющие комментарии

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

Пример кода на Python с поясняющими комментариями, объясняющими алгоритм сортировки пузырьком:

В этом примере поясняющие комментарии объясняют каждый шаг алгоритма сортировки пузырьком: как внешний цикл проходит по всем элементам, как внутренний цикл выполняет перестановки и как наибольший элемент «всплывает» на свою позицию в конце списка. Это помогает разработчикам понять логику алгоритма и его реализацию в коде.

Документирующие комментарии

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

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

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

— Описание неочевидных классов и методов. Документирующие комментарии предоставляют информацию о назначении, параметрах и возвращаемых значениях методов и функций.
— Генерация документации. Документирующие комментарии предназначены для автоматической генерации документации к коду и часто используются с инструментами типа Doxygen (для C++, C и других языков), Javadoc (для Java) и docstrings (для Python).

Допустим, у нас есть класс, реализующий алгоритм решения квадратного уравнения на Python:

Здесь документирующие комментарии описывают назначение класса QuadraticSolver, параметры его конструктора, метод solve() для решения уравнения и формат возвращаемых значений. Эта документация помогает понять, как использовать класс для решения квадратных уравнений, при этом она не избыточна и охватывает ключевые аспекты функциональности кода.

Отладочные и временные комментарии

Иногда в коде есть места, которые очевидно требуют доработки или улучшения в будущем. В таких случаях удобно использовать распространённые отладочные комментарии.

#TODO: Планирование рефакторинга

Этот комментарий используют, чтобы указать на необходимость будущего рефакторинга. Он обозначает, что конкретная часть кода требует доработки или оптимизации.

#FIXME: Исправление проблем

Комментарий #FIXME используют, когда обнаружили проблему или баг в коде, который нужно исправить. Этот тег помогает указать на участок кода, который может вызвать проблемы.

#Warning: Осторожный запуск

Тег #Warning подразумевает, что перед запуском соответствующего участка кода нужно быть осторожным из-за возможных проблем.

#Error: Обозначение ошибки

Комментарий #Error используют, чтобы указать на ошибки в коде. Здесь вы можете объяснить проблему и причину, почему её не удалось решить.

Пример кода с отладочными комментариями на Java:

В примере комментарий FIXME указывает на необходимость обработки случая деления на ноль, а комментарий TODO предполагает добавление логирования перед выполнением деления для последующей отладки.

Правила хорошего тона при комментировании

Написание хороших комментариев — искусство, требующее внимания к деталям и понимания потребностей. Пишите комментарии только там, где они действительно необходимы.

Вот несколько практик, про которые нужно помнить:

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

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

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

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

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

— Включайте контекст. Если код связан с какой-либо задачей, багом или требованием, включите ссылку на соответствующий номер или описание, чтобы разработчики могли понять, почему определённое решение было принято.

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

Когда комментарии в коде — плохая затея?

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

Вот несколько случаев, когда комментарии могут быть не нужны:

— Очевидные детали и стандартные конструкции. Не стоит комментировать простые и хорошо известные аспекты кода, которые понятны из его структуры. Комментарии, объясняющие базовые элементы языка программирования (например, что такое “for” или “if”), будут лишними.
— Неудачные попытки пояснения. Иногда попытка написать комментарий может только запутать, если код плохо структурирован. Вместо этого попробуйте улучшить сам код, чтобы необходимость в объяснении отпала.

— Излишне подробные описания. Если комментарии становятся слишком подробными и детальными, они могут усложнить чтение кода. Оставьте подробные объяснения для документации, а в коде пусть будут только ключевые моменты.

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

Подведём итог

Хорошо написанные комментарии могут значительно улучшить понимание и поддерживаемость вашего кода, а плохие — привести к путанице, ненужным сложностям и разозлить коллег.

Написание хороших комментариев — баланс между полезным объяснением кода и избеганием избыточности.

Кто умеет писать хорошие комментарии, поделитесь опытом, как к этому пришли.