Описание программы: структура, разделы и пример подготовки

Описание программы фиксирует, что делает программный продукт, из каких частей он состоит, в какой среде работает, какие данные использует и как связан с требованиями, архитектурой и эксплуатацией. По ГОСТ 19.402-78 этот документ помогает не просто описать код, а объяснить назначение, структуру и условия применения программы.

Хорошее описание программы должно быть понятно разработчику, аналитику, тестировщику, сопровождающей команде и принимающей стороне. Оно не заменяет ТЗ, HLD, SRS или LLD, но связывает их с конкретной программной реализацией.

• нужно подготовить комплект программной документации по ЕСПД или договору;
• программа передается заказчику, другой команде или в сопровождение;
• важно зафиксировать структуру модулей, данные, интерфейсы и среду работы;
• требуется связать разработку с требованиями, техпроектом и испытаниями;
• есть риск, что знания о программе останутся только в коде или у одного разработчика.

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

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

Структуру описания программы можно адаптировать под проект, но для ГОСТ-ориентированного комплекта важно не потерять назначение, состав, связи и условия работы программы.

Слабая формулировка: “программа предназначена для автоматизации учета”. Она слишком широкая и не показывает границы ответственности.

Рабочая формулировка: “программа предназначена для приема заявок от клиентов, проверки обязательных данных, маршрутизации заявок ответственным сотрудникам и передачи статусов во внешнюю CRM через API”. Такая формулировка показывает пользователей, основные действия, данные и интеграционный контур.

Описание программы находится между требованиями и детальной реализацией. Оно не заменяет ТЗ, SRS, HLD, LLD или рабочую документацию, а связывает их с реальной структурой программы.

• SRS и ТЗ отвечают на вопрос, что должна делать система и какие ограничения важны.
• HLD показывает крупные архитектурные решения и границы компонентов.
• LLD и рабочая документация раскрывают детальную реализацию, алгоритмы, классы, таблицы и настройки.
• Описание программы фиксирует состав, модули, связи, интерфейсы, данные и среду так, чтобы разработка, проверка и передача не зависели от устных объяснений.

• описывать только назначение без структуры программы;
• переписывать исходный код вместо объяснения модулей и связей;
• не фиксировать внешние зависимости, настройки и ограничения среды;
• смешивать назначение программы с перечнем всех функций;
• не указывать версии, связанные документы и способ проверки;
• оставлять устаревшие схемы после изменений архитектуры.

• Понятно, из каких модулей состоит программа и как они связаны.
• Есть граница между требованиями, архитектурой и реализацией.
• Команда может использовать структуру программы для планирования задач в tracker: модуль, интерфейс или зависимость превращаются в проверяемый участок работ.
• Проще передавать проект, проводить аудит, готовить испытания и объяснять систему новой команде.

• сформулировать назначение программы;
• проверить состав технического проекта;
• понять, когда нужен листинг программы.