Какая документация нужна?

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

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

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

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

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

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

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

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

7. Варианты. Какие функции может выбирать пользователь? Как этот выбор определяется?

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

9. Точность и проверка. Какова ожидаемая точность ответов? Каковы способы проверки точности?

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

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

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

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

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

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

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

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

1. Блок-схема или граф подчиненности подпрограмм. Последнее предпочтительней. (Подробнее обсуждается ниже.)

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

3. Форматы всех используемых файлов.

4. Схема передачи информации — последовательность считывания данных или программ с ленты или диска — и описание того, что происходит на каждом этапе передачи.

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

⇐ Предыдущая12131415161718192021Следующая ⇒

Поделиться: