Зачем вообще нужны какие-либо документы в процессе разработки? А как насчет этого утверждения, которое ? документирует сам код Рассмотрим наиболее распространенный сценарий: код системы (будь то программа, проект или продукт) пишется в течение длительного периода, и в ходе этого процесса команда постепенно меняется, забирая с собой определенные знания о системе по мере ухода разработчиков. Что мы можем сделать в таком случае? Самый простой ответ — , в которой будут отражены все детали реализации, чтобы гарантировать, что система соответствует первоначальным требованиям. написать спецификацию Однако такой документ очень сложно написать заранее, а в процессе разработки некоторые детали реализации могут измениться (адаптация к рынку/новые запросы на механику и т.п.). Итак, что мы можем придумать, чтобы улучшить ? коэффициент шины Давайте попробуем проследить последовательность действий, которая могла бы стать одним из возможных решений проблемы, упомянутой выше. Требования и RFC Во-первых, нам необходимо описать первоначальный проект на основе требований заинтересованных сторон и задокументировать его. После этого этим документом можно поделиться с другими командами и запросить у них обратную связь: попросить реализовать определенные функции, прокомментировать первоначальный дизайн, исправить определенный интерфейс и т. д. Такой документ можно назвать . RFC , или «Запрос на комментарии», — это документ, распространяемый среди заинтересованных сторон, включая разработчиков, архитекторов и другие команды, для сбора отзывов, комментариев и предложений. Она менее детальна, чем спецификация, и включает только исходную проблему, задачу и область решения. Будучи более гибким, он позволяет активно принимать изменения в проекте, обеспечивая глубокое понимание задачи и способствуя качественному и продуманному принятию решений. RFC Обязательства по проектированию и ADR Хорошо, мы и . Что дальше? определили технические требования собрали требования от других команд На этом этапе необходимо и всеми основными функциями, которые она будет выполнять. Для этого пишем . окончательно определиться с дизайном системы ADR , или «Запись архитектурного решения», — это документ, в котором фиксируются важные архитектурные решения, принятые в процессе разработки программного обеспечения. Каждый описывает конкретное архитектурное решение высокого уровня, его контекст, рассмотренные альтернативы, принятое решение и мотивацию выбора этих конкретных деталей среди других. ADR ADR Такой документ позволяет каждому члену команды (и другим командам) принципы и ценности, лежащие в основе дизайна. Если спустя годы к команде присоединится новый разработчик и спросит: «Почему вы сделали именно так?», ему можно показать этот документ, который ответит на все его вопросы. понять Спецификация Теперь пришло время написать код и его спецификации. На этом этапе мы тщательно прорабатываем каждую функцию, попутно объединяя всю информацию и детали реализации в специальный документ. Этот документ должен отражать текущие требования низкого уровня к системе. : в течение жизненного цикла ПО такая спецификация может существенно меняться, и это нормально. Однако очень важно оставаться в рамках исходного дизайна и архитектуры, чтобы кодовая база не превратилась в нечто неуправляемое. Важный момент План испытаний Зачем это нужно? Крайне важно, чтобы план тестирования строился , написанного по спецификации (мы пишем код и тесты для этого кода, чтобы они прошли), а на , включающего критические сценарии, которые . Также очень удобно, что такой план тестирования можно отправить на рассмотрение другим командам (для интеграции или просто для дополнительного тестирования), дав понять, как система будет вести себя в разных ситуациях. не на основе кода основе дизайна должны быть обработаны правильно Что это включает в себя? Все возможные сценарии работы системы Счастливый путь Печальный путь Обработка ошибок Все возможные инварианты, которые необходимо поддерживать в процессе работы системы. Приемочные тесты для проверки состояния системы в начале (следует учитывать среду, например, данные в сети) Мы завершили , написали код и и составили . Звучит уже довольно солидно! Но что еще мы могли бы добавить? проектирование спецификацию план тестирования План развертывания Такой план может быть необходим в некоторой степени для и создания условий, в которых любой член команды сможет развернуть систему и проверить ее состояние. улучшения коэффициента шины Почему мы не можем обойтись без этого? Мы можем, но в реальном мире большие команды, в которых за разные части системы отвечают многие люди, и процесс развертывания могут быть DevOps. Что в этом плохого, раз мы написали тесты, выложили их в CI и проверили на уязвимости, нужно ли нам что-то еще? Может и нет, но зачастую тесты не учитывают текущее состояние системы и тестируют не совсем то, что хотелось бы. полностью делегированы Какой план развертывания : может содержать Полное описание действий, которые необходимо выполнить, чтобы развертывание состоялось. Параметры развертывания: Переменные среды Начальное состояние Параметры для запуска План на случай, если что-то пойдет не так на любом этапе Запасной план, если это возможно Необходимое состояние, в которое необходимо привести систему в случае, если продолжение развертывания невозможно. Действия, которые необходимо выполнить после развертывания Уведомить другие команды Включите необходимые интеграции, если необходимо. Ничего сложного, правда? Наличие такого документа для конкретного обновления может значительно и от конкретных лиц. Разве не этого мы хотим? улучшить коэффициент шины предотвратить зависимость Заключение В процессе разработки программного обеспечения важно не просто писать код, но и создавать документацию, обеспечивающую понимание и последовательность на всех этапах разработки. Документацией , но опыт показал, что документация очень важна для поддержания качества, стабильности и будущей масштабируемости системы, особенно когда в процессе разработки меняется команда, а также когда проект развивается и адаптируется к новым требованиям. может быть сам код Документация включает (запрос комментариев), (записи архитектуры), , , и многое другое. Это позволит гарантировать , упростит процесс в проект, . RFC ADR спецификации планы тестирования планы развертывания сохранение знаний в команде интеграции новых сотрудников повысит общую надежность и устойчивость системы к изменениям
