В 2020 году я работал лидом в Chill Gaming на проекте Combat Quest — клон Archero. Первый проект, где я набирал команду под своё видение.
До этого я только читал важные и серьезные книги от Мартина Фаулера и Роберта Мартина и был на 100% уверен что обязательно разработка каждой фичи должна начинаться с ее проектирования кода и классов.
Потому каждая новая фича сопровождалась документом с детальным описанием классов и их связей между друг другом.
Не буду ходить вокруг, просто 3 факта из этого опыта:
1️⃣ Даже я сам читал документы по диагонали.
Уровень детализации слишком высокий, а логики в диаграммах нет. Толку в это вникать, если кода еще нет ...
2️⃣ Поддержка диаграмм отнимала ~20% времени разработки.
Код менялся быстрее, чем обновлялись схемы.
3️⃣ Побочный эффект: разработчики боялись лезть в задокументированные системы.
Изменения в коде системы = внесение изменений в документацию.
Это был первый прецедент, когда рекомендации из книг не сработали на практике.
🔸Что говорит C4 про уровень кода
В серии про проектирование мы прошли три уровня: система, контейнеры, компоненты. Остался четвёртый — код.
Сайт C4 model прямо говорит:
This is very much an optional level of detail... Ideally this diagram would be automatically generated using tooling.
Т.е. Simon Brown не рекомендует создавать диаграммы кода как долгоживущую документацию.
🔸Зачем тогда нужны диаграммы кода
Умение составлять диаграммы — не обязательный навык для разработчика.
Это инструмент коммуникации:
🔹С разработчиками на другом языке программирования
🔹Между разработчиками в команде — наглядное объяснение как подойти к реализации
Т.е. диаграмма кода — это не документация, а средство общения. Как салфетка с рисунком на митинге: нарисовал, обсудил, выбросил.
🔸Почему ручное проектирование кода избыточно
Уровни System, Container и Component описывают что система делает. Уровень Code описывает как это реализовано — классы, методы, связи.
Проблема в том, что:
▫️Диаграммы кода не содержат логики — отражают только структуру, но не поведение
▫️ Очень сложно адекватно отразить все связи реального класса так, чтобы это было удобно воспринимать
▫️ Код — самый волатильный уровень. Рефакторинг, новые требования, баг-фиксы — каждое изменение делает ручную диаграмму неактуальной
Документировать код вручную — фиксировать положение стрелки секундомера.
🔸Генерация вместо рисования
Если диаграмма кода всё-таки нужна — генерируй, не рисуй:
▫️ Mermaid — AI отлично генерирует Mermaid-диаграммы, а они из коробки рендерятся в любом .md файле. Самый быстрый путь от вопроса до схемы
▫️ Structurizr DSL — описание архитектуры as code. Есть MCP сервер — можно подключить к AI и генерировать диаграммы прямо из контекста проекта
▫️ Rider — умеет в Type Dependency Diagram, но НЕ в полноценные UML Class Diagram.
А то многие говорят что он научился, все еще нет.
Когда диаграммы уровня кода оправданы:
🔹Объяснение разработчику как подойти к реализации новой системы
🔹Проверка топологии системы перед рефакторингом
🔹Регуляторные требования (финтех, медтех)
И во всех случаях — генерируй, не надо их ручками рисовать.
🔻 Уровень кода не имеет смысла описывать формально — только для коммуникации. Как и уровень компонентов. Единственное, для чего он потенциально полезен — проверка топологии системы для рефакторинга. Верхние три уровня C4 формируют архитектуру. Четвёртый — нарисовал, обсудил, выбросил.
Ставь 👍 если тебе заходит такого рода контент!
Ты знаешь кому переслать эту статью 💪
#проектирование@UniArchitect