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

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

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

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

- Разработка с контрактов позволяет участникам работать параллельно.
- Генерация документации из кода - последовательно.

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

Все гибридные решения, например, в простой форме описывать API в wiki, а потом делать генерацию, — это monkey job. Нужно поддерживать документацию в двух местах, непонятно зачем.

Делитесь своим мнением в комментариях! 👇

#контракты #документация #разработка #API #архитектура #требования #команда #эффективность