Настоящий CTO: думай как технический директор - Алан Уильямсон

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

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

11.2.6. Комментарии в исходном коде

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

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

ЧТО?

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

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

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

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

КАК?

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

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

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

ЗАЧЕМ?

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

11.2.7. Схема архитектуры

Когда вам дарят коробку дорогих шоколадных конфет, на что вы смотрите в первую очередь? Конечно же, на схему, на которой указано, где лежат конфеты с разными начинками! Эта схема дает вам шанс избежать фундука, который прячется внутри. А истинные ценители шоколада используют ее для планирования своего гастрономического путешествия, ведь они хотят насладиться максимально насыщенным вкусом. Схемы и карты обеспечивают нас информацией, чтобы мы могли ориентироваться гораздо увереннее.

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

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

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

Слишком много деталей тут не нужно, это перегружает карту и делает ее трудной для понимания. Для каждого компонента (или штата, если говорить о карте) создайте отдельную схему, более подробную (уже с указанием местных дорог и городков).

Аналогия с картой особенно хорошо подходит для архитектур, использующих микросервисы и API. Как и в штатах США, крупные города и автомагистрали остаются неизменными, но местные дороги в каждом штате и городе постоянно развиваются.

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

11.2.8. Диаграммы процессов

Со схемой архитектуры тесно связаны диаграммы процессов. Они дают представление о том, как данные перемещаются по системе и что с ними происходит, когда они попадают в тот или иной сервис или библиотеку. Если схема архитектуры – это карта автомагистралей внутри штата или между ними, то диаграмма процесса – это наложенная на нее схема трафика из Google карт, показывающая, где находятся автомобили.

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

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

11.2.9. Схемы сети

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

Если у вас есть физические серверы, на этой диаграмме нужно показать их местоположение (например, адрес ЦОД и координаты стоек в нем). Характеристики каждого элемента оборудования, в том числе даты покупки, гарантийный срок и настройки конфигурации, можно будет указать в отдельных документах.

11.2.10. Схемы баз данных

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

Существует, однако, множество инструментов (например, DB Schema), которые могут проанализировать реляционную базу данных и сгенерировать ее схему, при этом на основании внешних ключей (foreign keys)