В сообществе разработчиков идет удивительно много страстных споров о полезности или желательности комментариев в исходном коде. Должен ли код включать существенные комментарии или вообще не содержать их, или что-то среднее?
Комментарии определяются как те строки текста, которые добавляются в исходный код после маркера определенного языка для обозначения нефункционального текста, явно игнорируемого компилятором или интерпретатором.
Цель комментариев
Одна из причин, почему разработчики пишут комментарии к своему коду: они отражают намерение.
Любой комментарий должен описывать то, что разработчик намеревается сделать целью или результатом раздела кода. Но несмотря на это, комментарии никогда не должны повторять функциональность кода.
Против комментариев
Некоторые разработчики яро выступают за то, чтобы комментировать как можно меньше или вовсе этого не делать. Один из главных аргументов – это поговорка: «Хороший код самодокументируется». Основывается она на том, что прокомментированный код часто труднее понять, нежели код без комментариев. Но есть ещё ряд причин, почему разработчики отказываются от комментирования:
Время. Комментарии занимают много времени, как и их поддержка. Разработчики предпочитают тратить время не на объяснение своего кода, а на его написание.
Не соответствие. Со временем комментарии непреднамеренно могут лгать, что может привести к неправильно интерпретации кода.
Длина. Комментарии делают файл длиннее и часто могут внести ненужный беспорядок, что требует больше времени для чтения.
Повторение кода. Комментариями часто пытаются объяснить «что и как», что имеет тенденцию просто повторять код. Комментарии всегда должны указывать «почему».
Конкретность. Писать ясные, а не загадочные комментарии сложно, а интерпретировать их тем более. Если код был написан запутанным образом, то, вероятно и комментарий будет такой же.
Несвязность. Иногда комментарии пишут разработчики, которые неправильно понимают код, и усиливают это непонимание неправильным или вводящим в заблуждение текстом.
За комментарии
Намеренное комментирование имеет преимущества, несмотря на недостатки. Прежде всего, комментарии помогают тому, кто их написал. Следующая причина, но немаловажная, – они могут облегчить понимание другим.
Время на чтение и понимание кода сокращается
Поскольку с помощью комментариев вы знаете, что должно произойти, это дает вам основу для интерпретации этого участка кода. Особенно это может пригодиться, если вы пытаетесь вернуться в нужное русло после перерыва.
Поиск конкретного функционального раздела кода становится проще
Найти какой-то конкретный код в большом незнакомом проекте будет легче, если он будет содержать комментарии. Без них придется просматривать сотни и тысячи файлов и тратит время на их чтение. Инструменты поиска помогают только в том случае, если вы можете угадать имя функции. Намеренные комментарии дают вам точку опоры.
Вы можете реконструировать модели мышления разработчика
Уместный комментарий с намерением отвечает на вопрос: «Что предыдущий разработчик собирался здесь делать?».
Несоответствие между закомментированным намерением и фактическим результатом кода указывает на потенциальные ошибки
Ошибку проще обнаружить, если код будет содержать комментарий о намерениях. Например, разработчик намеревался сделать одно, а код не соответствовал этим намерениям.
Непрограммисты тоже смогут участвовать
Руководитель, клиент, дизайнер, пользователь открытого исходного кода и т.п. также смогут просмотреть ваши комментарии и лучше понять, что происходит. Поскольку комментарии о намерениях не зависят от языка, они обеспечивают основу для полезной обратной связи.
Код автоматически становится учебным пособием
Стажеры могут прочитать определенные разделы кода с комментариями, если что-то не понимают. Это позволит им изучит даже продвинутые и сложные шаблоны и алгоритмы.
Дискуссия о комментариях в коде не нова. Есть веские аргументы за и против них. Да, комментирование стоит времени разработчику при написании, но экономит время другим при понимании кода на позднем этапе. Главное добавлять осмысленные комментарии, чтобы улучшить читабельность кода.