Какая документация требуется?

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

Чтобы использовать программу. Каждому пользователю требуется словесное описание программы. По большей части документация страдает отсутствие общего обзора. Описаны деревья, прокомментированы кора и листья, но план леса

* Томас Дж. Уотсон Старший — основатель компании IBM (примеч. перев.)

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

1. Назначение. Что является главной функцией программы и причиной ее написания?

2. Среда. На каких машинах, аппаратных конфигурациях и конфигурациях операционной системы будет она работать?

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

4. Реализованные функции и использованные алгоритмы. Что конкретно может делать программа?

5. Форматы ввода-вывода, точные и полные.

6. Инструкция по работе, в том числе описание вывода на консоль и устройство вывода при нормальном и аварийном завершении.

7. Опции. Какой выбор предоставляется пользователю в отношении функций? Каким образом нужно его задавать?

8. Время работы. Сколько времени занимает решение задачи заданного размера на заданной конфигурации?

9. Точность и проверка. Какова ожидаемая точность результатов? Какие имеются средства проверки точности?

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

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

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

Кроме того, нужны более тщательные тесты, которые обычно выполняются только после модификации программы. Они относятся к трем участкам области входных данных:

1. Основные параметры, проверяющие главные функции программы на обычно встречаемых данных.

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

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

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

1. Блок-схема или граф подпрограммной организации. Подробнее об этом см. ниже.

2. Полные описания используемых алгоритмов или ссылки на такие описания в литературе.

3. Разъяснение структуры всех используемых файлов.

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

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

Бич блок-схем

Блок-схема чаще всего является лишней частью программной документации. Для многих программ блок-схемы вообще не нужны. Редкие программы требуют блок-схемы более чем на одну страничку.

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