Если вы хотите вовлечь разработчиков в спор, по накалу страстей не уступающий легендарной дискуссии о табуляции и пробелах (кстати: пробелы), спросите, сколько комментариев должно быть в коде. Ответы будут варьироваться от «Моему коду комментарии не нужны – он и так понятен» до «Да уж, без комментариев тут не разберешься».

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

ЧТО?

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

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

Отличным примером является язык Java, в котором есть стандарт для написания документации для классов и методов, он называется Javadoc. Такая документация не только показывается при использовании автодополнения кода и других функций IDE, на ее основе также можно сгенерировать набор веб-страниц с описанием исходного кода. Другой пример – библиотека Swagger, которая предназначена для создания документации в формате HTML для различных API, и, кроме этого, содержит инструменты для выполнения запросов к API для его тестирования или изучения.

Большое преимущество подобной документации состоит в том, что она находится в том же файле, что и код, поэтому ее легко обновлять. Документация в исходном коде очень важна, особенно для больших команд или в тех случаях, когда ваше API используется внешними клиентами.

КАК?

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

Идеальным будет оставлять в комментариях ссылки на тикеты – это поможет следующему разработчику лучше понять, почему компонент делает именно это. Какой-нибудь неочевидный оператор if можно легко объяснить, добавив номер тикета, и тогда следующий разработчик не будет его рефакторить в уверенности, что помогает проекту, но на самом деле добавляя еще больше проблем.

Убедитесь, что при ревью кода проверяется и достаточность комментариев. Когда разработчики привыкнут это делать, они уже не смогут работать без документации.

ЗАЧЕМ?

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