Григорий Петров: Зачем в коде комментарии

[button color=4d61d7 icon=arrow-left-2 url=https://apptractor.ru/develop/grigoriy-petrov-priruchenie-neizbezhnosti.html] Предыдущая статья [/button]

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

«Все знают», что исходный код надо комментировать. Но спроси любого разработчика, что именно и как надо комментировать, и вы с удивлением услышите, что у большинства разработчиков свое уникальное мнение в этом вопросе. А многие к тому же считают, что требование комментировать код — это блажь тим лида. Который, в свою очередь, требует «хоть каких-то» комментариев потому, что знает, что «так вроде правильно». В результате одни программисты комментируют каждую строчку, теряя на этом огромное количество времени. Другие пишут огромные «шапки» к каждому методу, оставляя сам код без единого комментария. Третьи под давлением тим лида широкой рукой сеют в комментариях труизмы, дублирующие уже имеющуюся в коде информацию, и бесполезные чуть менее, чем полностью.

На мой взгляд, комментарии в коде — это важный инструмент в борьбе со сложностью, и его правильное применение вместе с другими инструментами позволяет значительно снизить риски при разработке и сделать дальнейшую поддержку разработанного менее болезненной. Исторически сложилось, что за комментированием исходного кода следит тим лид. Задача менеджера — при найме тим лида выбрать из кандидатов того, кто понимает необходимость работы с комментариями, сможет объяснить это команде и следить за работой бойцов. А менеджеру, в свою очередь, нужно внимательно следить за работой тим лида, ибо в пословице «доверяй, но проверяй» все-таки есть рациональное зерно.

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

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

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

Комментарии являются самым «близким» к коду местом, куда можно вынести сложность, если в самом коде ее скопилось много и мы по каким-то причинам не хотим или не можем распределить эту сложность по самому коду. Обратите внимание на этот, на мой взгляд, ключевой момент: основное назначение комментариев – это «вытягивание» на себя сложности из кода. А не «рассказ о коде», как очень часто считают разработчики.

Когда и как писать комментарии

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

Идеальный код сам способен ответить на оба ключевых вопроса: «что это» и «зачем это». Но такой код встречается редко. Большинство опытных программистов способны писать код, который сам по себе отвечает на вопрос «что это». Они используют «говорящие» имена идентификаторов, правильное разделение кода на части, постоянный контроль кошелька Миллера и много других интересных приемов. С вопросом «зачем это» сложнее; быстро писать код, который бы отвечал на оба вопроса, способны далеко не все разработчики. И как раз в таких ситуациях на помощь приходят комментарии: с их помощью можно в ключевых местах добавлять ответы на вопросы «зачем» — не в сам код, а рядом с ним, что позволяет держать сложность под контролем.

Как это знание помогает менеджеру?

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

Если руководитель проекта хочет, чтобы проект получился и получился хорошо, то контролировать надо всех. В разумных пределах, конечно. Микроменеджмент тоже до добра не доводит. Как менеджер может проверять правильное использование комментариев в коде? Основываясь на рассказанном выше, можно использовать две проверки:

• Раз в несколько дней просматривать код и смотреть, что комментариев не слишком много. Если вы видите, что разработчики фанатично делают «шапку» комментариев к каждой функции, а вы разрабатываете совсем не набор комментированных функций для других разработчиков, то это один из признаков «карго культа», что не есть хорошо. Беседа с тим лидом о том, почему же ни одна функция не способна без комментария ответить на вопросы «что это?» и «зачем это?» помогает нормализовать ситуацию.
• Раз в несколько дней выбирать случайный кусок кода, случайного программиста и спрашивать его «расскажи, зачем этот код». Если программист не может быстро ответить на такой вопрос, или вместо ответа на вопрос «зачем» пытается ответить на вопрос «что» — значит сложность кода не выносится в комментарии (или другие места), и об этом тоже небесполезно будет побеседовать с тим лидом.

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