Составление документации по архитектуре и API модулей игр

id: 227 slug: game-module-architecture-and-api-documentation title_ru: "Составление документации по архитектуре и API модулей игр" tags: [vr-ar]

Составление документации по архитектуре и API модулей игр

Документация пишется не для порядка. Она пишется в тот момент, когда новый программист за три часа не может понять, почему EventBus.Publish<PlayerDiedEvent>() вызывает перезагрузку сцены в одном месте, а в другом — только обновляет UI. Или когда через полгода сам автор кода не помнит, зачем в InventoryModule есть внутренний кэш на 50 слотов поверх основного хранилища.

Что делает документацию по игровым модулям действительно полезной

Главная ошибка — документировать «что делает метод», когда это и так видно из сигнатуры. /// <summary>Adds item to inventory</summary> над AddItem(Item item) — бесполезная строка. Ценная документация отвечает на три вопроса: почему это сделано именно так, что произойдёт в граничном случае и с чем это взаимодействует.

Для игровых проектов особенно важна документация по состояниям и зависимостям. Модуль SaveSystem, который работает через PlayerPrefs в Editor и через облачный API в продакшене, — это неочевидное поведение, которое нужно явно описать. Иначе разработчик пишет тест, который проходит локально и падает на устройстве.

Второй пласт — документация по потокам данных между модулями. В Unity-проектах с Zenject или VContainer зависимости инжектируются, и IDE не всегда подсказывает, откуда пришёл конкретный сервис. Architectural Decision Record (ADR) на одну страницу с диаграммой зависимостей экономит часы при онбординге.

Структура документации для игрового проекта

Для модульной игровой архитектуры строим документацию на нескольких уровнях:

Обзор архитектуры — диаграмма модулей и их зависимостей (PlantUML или Mermaid, встраивается прямо в Markdown в Confluence/Notion). Обязательно: слои (Presentation, Domain, Infrastructure), направления зависимостей, что является Singleton, что создаётся через фабрику.

Модульные карточки — для каждого крупного модуля: назначение, публичный API, события которые испускает и на которые подписывается, требования к инициализации (порядок Awake/Start), известные ограничения.

API Reference — генерируем из XML-комментариев через DocFX или Doxygen. Для C# Unity-проектов DocFX даёт чистый HTML с навигацией. Настраиваем автогенерацию в CI: при каждом пуше в main обновляется документация на внутреннем сервере.

Сценарии использования — конкретные примеры кода для неочевидных случаев. Не public void Initialize() с описанием параметров, а «как правильно инициализировать WeaponSystem в сцене, где нет PlayerController в момент старта».

Для VR/AR-проектов добавляем раздел XR Interaction Flow: описание последовательности событий от SelectEntered до SelectExited в XR Interaction Toolkit, маппинг кнопок контроллера, специфика работы с разными HMD (Quest vs Pico vs HTC Vive).

Инструменты и форматы

DocFX — стандарт для C#/.NET проектов, хорошо работает с Unity. Генерирует сайт из XML doc-comments + ручных Markdown-страниц.

Doxygen — если проект на C++ (Unreal Engine). Поддерживает диаграммы через Graphviz.

Mermaid — для архитектурных диаграмм прямо в Markdown-файлах. Рендерится в GitHub, GitLab, Notion, Confluence.

Confluence + структурированные шаблоны — если команда уже на Atlassian-стеке. Создаём шаблоны страниц для модулей, чтобы документация была однородной.

Комментарии в коде пишем по конвенции XML doc (C#): <summary>, <param>, <returns>, <exception>, <remarks> — последний используем для неочевидных деталей поведения.

Как строится работа

Аудит существующей кодовой базы. Читаем код, выявляем неочевидные паттерны, точки связи между модулями, нестандартные решения.

Интервью с разработчиками. Задаём вопросы по решениям, которые не объяснены в коде. Записываем как ADR.

Создание структуры документации. Определяем, где живёт документация (Confluence, GitHub Wiki, отдельный DocFX-сайт), какой формат для каких задач.

Написание и разметка. Документируем модули по приоритету: сначала самые критичные и самые непрозрачные.

Настройка автогенерации. CI-пайплайн для обновления API Reference при изменениях кода.

Ревью с командой. Разработчики подтверждают корректность, выявляем пробелы.

Стоимость определяется после анализа объёма кодовой базы и требований к формату документации.