Программная документация

Афоризм: “Program without documentation is a garbage.”

Виды документации ПП:

· Проектная - результаты всех этапов разработки; используется при проектировании и сопровождении.

· Эксплуатационная - адресованная конечным пользователям и эксплуатационникам (системным администраторам)

Кроме того, существует нормативная документация - в ней зафиксирована технология разработки ПП, принятая на данном предприятии. К ней относятся:

- технологические инструкции по всем этапам разработки, в частности, стандарт кодирования (Coding Standard or Convention)

- шаблоны программных документов

Проектная документация (ПД)

Список проектных документов, рекомендуемых в стандарте ISO 9000-3:

1. Marketing (or Customer) Requirements

2. Software Requirements Specification

3. Project Development Plan

4. Software Design Document(s)

5. System Test Specification

6. Alpha Evaluation Plan

7. Beta Evaluation Plan

Их рекомендуемое содержание раскрывется в чересчур бюрократической манере, например: System Test Specification Template – шаблон спецификации комплексного тестирования (см. Приложение 4.1; Вопрос 1.).

На практике каждая организация имеет свой перечень ПД и их шаблоны. Ключевое понятие: спецификация – по возможности максимально точное и полное описание (требований, проектных решений, тестов). Документы 1 и 2 из списка ISO содержат результаты анализа задачи (например, предпроектного обследования предприятия для АСУ). Вместе с документом 3 они содержат то, что принято называть техническим заданием или внешней (функциональной) спецификацией ПП. Это – основной отчуждаемый проектный документ, играющий роль контракта между производителем и потребителем и отправной точки для других проектных и эксплуатационных документов. Его рекомендуемое содержание состоит из трех частей (см. также рекомендуемый шаблон ниже и Приложение 4.2):

1. Общая характеристика

Цели, требования, ограничения – технико-экономическое обоснование проекта. Составляется системными аналитиками совместно с заказчиком.

2. Информационная и функциональная структура

Составляется системными аналитиками и программистами и адресовано в основном разработчикам как ТЗ на детальное проектирование, а также заказчикам – в части внешнего интерфейса. Здесь также обосновывается достижимость (feasibility) целей, поставленных в части 1.

3. План тестирования

Контракт на приемо-сдаточные испытания (acceptance test) и спецификация комплексного тестирования (system test), т.е. ТЗ на разработку соответствующих тестов. Составляется системными аналитиками.

Удельный вес и детальность проработки этих частей может быть различной для разных видов ПП, но следует придерживаться принципа приоритетности раннего связывания (”Не откладывай на завтра то, что можно сделать сегодня”) – т.е. фиксировать все характеристики и проектные решения в 1 и 2 частях, очевидные заранее, например, известные из прототипа или уже существующего аналогичного ПП. (Известно, что раннее связывание дешевле позднего - ср. статическое и динамическое связывание указателей в программировании.) Это же относится к плану тестирования, который рекомендуется разрабатывать до этапа реализации ПП. На этапе сопровождения внешняя спецификация служит "техническим паспортом" ПП.

Типовой шаблон внешней спецификации программного продукта

Рекомендуется для документирования программ в бакалаврских и магистерских диссертационных работах и в самостоятельных НИР: