Почему комментарии в коде — базовый инструмент, упрощающий поддержку и развитие проекта
Привет, Хабр! На связи C#-разработчик компании SimbirSoft Георгий. В этой статье поговорим о том, как с помощью комментариев кода можно ускорить погружение новых разработчиков в проект, упростить написание документации и найти общий язык с коллегами-разработчиками. Отмечу, что это рекомендации, основанные на собственном опыте, и вы можете быть с ними не согласны.
Материал будет интересен как начинающим IT-специалистам, кто только учится писать чистый и красивый код, так и тем, кто отвечает за формирование кодстайла проектов. Подкреплять свои рассуждения буду примерами из личного опыта и опыта коллег. Сначала быстро пройдемся по основам, а потом откроем этот ящик Пандоры и уйдем в рассуждения.
База
Обзорно начнем с базы. Рассматривать все будем в VisualStudio 2022 (разницы особо нет, но лучше уточнить).
Итак, комментарии нужны для более подробного описания методов, классов интерфейсов, да и в целом чего угодно. Они дают более подробное понятие разработчику о том, что этот метод/класс делает и что от него ожидать.
Рассмотрим простой пример бесполезного метода:
///
/// Описание метода.
///
/// Входной параметр.
/// Возвращаемые данные.
/// Ошибки.
public static string GetBase(int parameter)
{
throw new NotImplementedException();
} Для описания используются следующие теги:
///
/// Описание метода.
/// Непосредственно описание того, что метод делает:
/// Входной параметр.Описание входных параметров метода:
/// Возвращаемые данные. Описание возвращаемого значения, если такое есть:
/// Ошибки. Ошибки, которые могут возникнуть в результате его выполнения.
Также достаточно часто используется тег
/// Он применяется в связке «интерфейс — реализация» и навешивается на методы реализации, если у интерфейсных методов есть описание. Позволяет более явно указать, что у метода есть комментарий, но он будет взят из соответствующего метода интерфейса (или базового класса).
В целом, можно обойтись и без него, потому что описание методов интерфейса и так автоматически подтянется.
Более подробно обо всех существующих тегах и их значениях описано в официальной документации.
Чтобы самому приходилось меньше писать руками, в Visual Studio (как, наверняка, и в любой другой IDE) существуют сниппеты, которые позволяют генерировать шаблоны для таких комментариев. В той же Visual Studio можно ввести
///над названием метода или интерфейса, и IDE сама сгенерирует полноценный шаблон со всеми полями, ошибками и возвращаемыми значениями. Лучше генерировать комментарий после того, как метод закончен, чтобы потом не приходилось уже самому редактировать его, менять входные параметры и делать то, чего мы хотели избежать, используя этот сниппет. Аналогичную функциональность в других IDE стоит уже искать в соответствующей документации.
А теперь перейдем к основной части с примерами.
Проблема и возможный путь ее решения
Часто можно услышать от разработчиков, что комментарии в коде не нужны, что они отнимают время, да и вообще код должен быть самоописываемым, чтобы и так все было понятно.
Здравый смысл в этом есть. Хороший код должен быть понятен и не порождать вопросов о его предназначении. Но так получается далеко не всегда. Рассмотрим самый вероятный пример, который может произойти с каждым.
Разработчик устраивается на новую работу. Так получилось, что его новый проект — легаси десяти лет от роду, документация которого была утеряна во времена наполеоновских войн, а кор-команда разработчиков пропала без вести на необитаемом острове. Глоссарий собирался разными специалистами в разные моменты существования проекта и очень неполный. Комментариев в коде нет, а аналитик с лидом в рабстве постоянных созвонов.
Перспективы быстро вникнуть весьма удручающие, но что делать — оффер уже подписан, надо разбираться. Можно смело заявить, что разработчику потребуется немало времени, чтобы глубоко погрузиться в проект. Естественно, что он будет обращаться к своей команде за помощью, чтобы понять, что вообще должно происходить в системе. Это всё время, а время — это деньги. Чем быстрее новый сотрудник освоится, тем быстрее он начнет работать в полную силу.
Использование комментариев не поможет найти пропавшую документацию или вернуть кор-команду разработчиков с необитаемого острова. Однако уже новые доработки и затронутые старые блоки кода будут намного понятнее с грамотно написанными комментариями. Это позволит разработчику лучше ориентироваться в коде (он вспомнит, что уже залезал в этот метод, и быстро поймет, что там происходит), и поможет последующим поколениям команд понимать первоначальную задумку.
Пример утрированный, но весьма показательный. Если проект большой и существует уже долгое время, то скорее всего что-то забылось, что-то потерялось, кто-то где-то прикрутил «велосипед без колес». Комментарии помогут в понимании разработчиков друг друга и объяснят, почему в коде есть велосипед и зачем он горит.
Если проект уже какое-то время развивается, на его рефакторинг не дадут ни времени, ни денег, поэтому самое быстрое и не затратное решение — написать комментарии там, где довелось поработать. Потратить 10–15 минут на написание развернутых комментариев для каждой новой фичи звучит, как душное занудство, но эти 10–15 минут сейчас экономят часы в будущем. Речь идет не о комментировании каждой строчки кода, а о добавлении документирующих комментариев к методам, классам и так далее, которые будут отражать общую суть выполняемых действий.
Теперь представим, что разработчику достался классный проект, у которого есть полная и понятная документация. Казалось бы, зачем в нем комментарии? А чтобы не отрываться от процесса написания кода. Благодаря комментариям можно по ходу работы получить информацию о предназначении тех или иных методов и не лезть в документацию.
Коротко по делу: когда комментарии могут упростить разработку
1. Предсказуемость методов в случае сбоев
Если метод может кидать какие-либо ошибки, типы этих ошибок можно подсветить в комментарии к методу. Тогда при его использовании разработчик увидит, что ожидать от метода в случае сбоев и добавит обработку этих ошибок. Поведение методов становится предсказуемее, что позволяет организовывать гибкую обработку ошибок для конкретных сценариев.
Очень удобно, если используется какой-либо хелпер/парсер или что угодно другое без интерфейса. Тогда из клиентского кода можно понять, что может пойти не так, завернуть это в try catch и уже тут разбираться, что мы хотим делать с ошибкой. Не то чтобы мне часто доводилось этим пользоваться, но была пара случаев, когда такого рода комментария не хватало.
Например, так это может выглядеть:
2. Простая поставка библиотек
Допустим, у нашего приложения есть самописная библиотека, которая понадобилась другой команде. В случае, если у библиотеки есть комментарии, разработчикам из другой команды будет проще в ней разобраться, и они будут реже дергать нашу команду ради пояснений. За примером далеко ходить не надо: можно навестись на любой метод любого класса в нашем любимом .NET и увидеть краткое описание того, что этот метод делает.
3. Ускоренное погружение новых сотрудников
Наличие простых и понятных комментариев в коде позволяет разработчику лишний раз не бегать в документацию, не дергать лида или аналитика для того, чтобы понять, что есть что. Вся терминология и поверхностное описание процессов приложения уже находятся под рукой, а если быть точнее — перед глазами в коде. И как показывает практика, такого понимания контекста хватает для реализации поставленных целей в начальный период пребывания на проекте. Как показала моя практика и опыт коллег, в этом случае грейд нового сотрудника абсолютно не важен — новый член команды всегда адаптируется быстрее, если код покрыт комментариями.
4. Упрощение код-ревью и шаринг знаний
В данном пункте одно вытекает из другого. Код-ревью упрощается за счет того, что человек, не имеющий отношение к новой функциональности, может понять глобальную задумку и уже более детально проанализировать, что автор кода пытался сделать. Таким образом, процесс осознания происходящего занимает меньше времени, а разработчики, занятые другими задачами, могут поверхностно понять, что происходит в другой части их проекта. Таким образом, повышается осведомленность всей команды о том, куда движется проект, какие классы и методы можно будет переиспользовать для себя.
5. Глоссарий в коде
Отдельный документ, где собрана терминология всех бизнес-сущностей проекта — штука клевая и полезная, однако не совсем удобная. Не всегда быстро можно найти нужную вкладку и пройтись по странице поиском. Комментарии позволяют на ходу понять, что есть что, не перегружая сотрудника информацией, которая на данном этапе ему не нужна.
А что комментировать-то?
Без фанатизма. Главное, чтобы были описаны методы, классы, интерфейсы, входные параметры методов и их возвращаемые значения. Вообще прекрасно, если описаны модели, их свойства, названия. Не всем импонирует идея прописывать для свойств уровня ObjectId «идентификатор объекта», но с другой стороны, никто не гарантирует, что в будущем модель не расширят (появится еще пара айдишников), не добавят сложных и непонятных с первого взгляда свойств. В этой ситуации я рекомендую придерживаться единообразия. Если комментарий есть на одном свойстве/методе, то он должен быть везде. Так и код выглядит аккуратнее, и не будет мыслей вроде: «Так, я только что видел же описание этого свойства, а на другом оно где? А было ли первое описание вообще? А может, тут другая логика, раз описания нет?».
Что в итоге?
В конце хотелось бы добавить, что тема комментариев в коде весьма холиварная, и даже у моих коллег нет однозначного мнения по этому поводу. Лично мой опыт говорит мне, что при заходе на новый проект мне будет куда проще вникать, будь у него осознанные и адекватные комментарии. Писать их иногда бывает слишком душно, не спорю, и сам могу оставить на последний момент перед коммитом. Зато как красиво выглядит код, и как просто в нем ориентироваться, когда еще ничего непонятно, но очень интересно.
Больше авторских материалов для backend-разработчиков от моих коллег читайте в соцсетях SimbirSoft — ВКонтакте и Telegram.
