7.4. Документация на разработанный программный продукт

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

1. Описание задачи, которую решает данная программа.

2. Область применимости программы, т. е. класс исходных данных, на которые рассчитана программа, и степень, контроля за принадлежностью данных этому классу.

3. Описание использованного метода (расчетные формулы или словесный алгоритм), желательно со ссылками на литературу.

4. Исходные данные, необходимые для работы программы, выдаваемые результаты и производимый побочный эффект. Исходные данные понимаются в широком смысле: так имя подпрограммы вычисления подынтегрального выражения для программы вычисления определенного интеграла - также исходное данное. Для каждого данного необходимо указать тип, размер и т. п., а также область допустимых значений; целесообразно при этом дать указание о наличии в программе контроля за принадлежностью к этой области.

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

5. Правила подготовки исходных данных для ввода.

6. Список использованных переменных (переменные понимаются в широком смысле, включая и массивы). Необходимо выделить исходные данные и результат (для подпрограммы это ее параметры). Отдельно перечислить вспомогательные переменные. Для каждой переменной необходимо указать ее связь с исходной постановкой задачи, а также ее формальные характеристики в программе: тип, размер, и т. д. (например, К - вещественный массив размером 100, результаты соревнований, Р - символьный массив размером 100 с длиной элемента 16, фамилии участников и т. д.).

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

8. Текст - программы (в виде распечатки).

9. В тестах должны задаваться исходные данные и конечные результаты работы программы. Тесты необходимы при модификации программы, перенесении ее на другой тип вычислительной техники или при пepeводе на другой язык программирования.

Инструкция по использованию программы. Инструкция - это выдержка из полной документации, предназначенная для эксплуатации программы. В инструкции описывается, что делает программа и как ею пользоваться.

Первая часть содержит краткую характеристику реализованного в программе метода и ссылку на литературу, содержащую его полное описание. Вторая часть должна описывать порядок обращения к программе, в частности исходные данные и результат (для подпрограммы - параметры), правила подготовки данных для ввода, а также форматы печати. Инструкция должна содержать сведения обо всех режимах работы программы (если их несколько) и обо всех выводимых результатах или сообщениях, выдаваемых по ходу выполнения программы.

Во многих случаях, однако, эти инструкции не являются полными. Их цель - не обеспечить возможность использования программы вслепую, а показать связь между постановкой задачи и приведенной в качестве примера программой.