В сообществе разработчиков программного обеспечения существует единое мнение, что документирование необходимо. Но в то же время, это не самая гламурная задача, особенно по сравнению с написанием кода. Поэтому для нас, разработчиков, вполне естественно задуматься:
А что если я буду генерировать документацию из исходного кода?
Я использовал этот подход в нескольких проектах, но в последние годы я придерживаюсь несколько иного подхода, который я называю «сначала документация». Я проиллюстрирую это на примере.
Представьте себе команду, состоящую из бэкенд- и фронтенд-разработчика. Эта команда должна решить следующую задачу:
Разработать форму регистрации продукта
Во время доработки я всегда предлагаю команде разбить эту задачу на подзадачи, например:
- Определить контракт API
- Разработать API
- разработать форму
- и т.д.
В контексте данного поста существенной является только первая задача. В ней команда совместно работает над определением контракта API. Они обсуждают формат данных, будет ли API Rest или RPC, аутентификацию, сжатие данных и другие важные вопросы. Результатом этой задачи является документация, желательно в стандарте OpenAPI или API Blueprint (я предпочитаю этот формат).
После выполнения этой задачи они снова могут работать параллельно. Бэкенд-разработка будет сосредоточена на предоставлении определенного API, в то время как фронтенд будет реализовывать форму, зная, что он будет отправлять и получать от бэкенда. Кроме того, если они напишут документацию с использованием одного из вышеупомянутых стандартов, то создание макетов и заглушек станет возможным, что упростит разработку и тестирование.
Конечно, в процессе разработки команда может столкнуться с некоторыми побочными ситуациями, которые они не заметили на этапе подготовки документации. Когда это случается, необходимо быстро переделать документацию, и работа идет своим чередом.
Используя этот подход, я обнаружил некоторые преимущества, такие как:
- команда тратит больше времени на обдумывание сценариев, в которых будет применяться API, создавая большее понимание до написания любой строчки кода;
- улучшается взаимопонимание между членами команды;
- документация остается актуальной и живой.
Здесь я использовал пример разработки API. Тем не менее, тот же подход можно применять и в других сценариях, особенно там, где у нас есть интеграция между частями системы, например, в среде микросервисов.
Как я уже говорил, я использую этот подход в течение последних нескольких лет, и результат оказался очень достойным. Надеюсь, он имеет смысл для вашей команды, и если да, то поделитесь своим опытом в комментариях.