Что вы знаете о разработке, управляемой документами?

Зачем вообще нужны какие-либо документы в процессе разработки?

А как насчет этого утверждения, которое документирует сам код ?

Рассмотрим наиболее распространенный сценарий: код системы (будь то программа, проект или продукт) пишется в течение длительного периода, и в ходе этого процесса команда постепенно меняется, забирая с собой определенные знания о системе по мере ухода разработчиков.

Что мы можем сделать в таком случае?

Самый простой ответ — написать спецификацию , в которой будут отражены все детали реализации, чтобы гарантировать, что система соответствует первоначальным требованиям.

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

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

Требования и RFC

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

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

Обязательства по проектированию и ADR

Хорошо, мы определили технические требования и собрали требования от других команд . Что дальше?

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

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

Такой документ позволяет каждому члену команды (и другим командам) понять принципы и ценности, лежащие в основе дизайна. Если спустя годы к команде присоединится новый разработчик и спросит: «Почему вы сделали именно так?», ему можно показать этот документ, который ответит на все его вопросы.

Спецификация

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

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

План испытаний

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

Что это включает в себя?

• Все возможные сценарии работы системы

  • Счастливый путь
  • Печальный путь
  • Обработка ошибок

• Все возможные инварианты, которые необходимо поддерживать в процессе работы системы.

• Приемочные тесты для проверки состояния системы в начале (следует учитывать среду, например, данные в сети)

  
  

Мы завершили проектирование , написали код и спецификацию и составили план тестирования . Звучит уже довольно солидно! Но что еще мы могли бы добавить?

План развертывания

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

Почему мы не можем обойтись без этого? Мы можем, но в реальном мире большие команды, в которых за разные части системы отвечают многие люди, и процесс развертывания могут быть полностью делегированы DevOps. Что в этом плохого, раз мы написали тесты, выложили их в CI и проверили на уязвимости, нужно ли нам что-то еще? Может и нет, но зачастую тесты не учитывают текущее состояние системы и тестируют не совсем то, что хотелось бы.

Какой план развертывания может содержать :

• Полное описание действий, которые необходимо выполнить, чтобы развертывание состоялось.
• Параметры развертывания:
  • Переменные среды
  • Начальное состояние
  • Параметры для запуска
• План на случай, если что-то пойдет не так на любом этапе
• Запасной план, если это возможно
• Необходимое состояние, в которое необходимо привести систему в случае, если продолжение развертывания невозможно.
• Действия, которые необходимо выполнить после развертывания
  • Уведомить другие команды
  • Включите необходимые интеграции, если необходимо.

Ничего сложного, правда? Наличие такого документа для конкретного обновления может значительно улучшить коэффициент шины и предотвратить зависимость от конкретных лиц. Разве не этого мы хотим?

Заключение

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

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