Мифический человеко-месяц или как создаются программные системы
Шрифт:
Глава 15 Обратная сторона
Чего мы не понимаем, тем не владеем.
ГЕТЕ
О, дайте мне выступить комментатором, Скользящим по поверхности и будоражащим умы.
КРАББ
Компьютерная программа — это послание человека машине. Строго выстроенный синтаксис и тщательные определения нацелены на то, чтобы бездумной машине стали понятны намерения человека.
Но у написанной программы есть обратная сторона: она должна быть в состоянии рассказать о себе
Насколько же более необходима документация для программы общего пользования, пользователь которой отдален от автора во времени, и в пространстве! Для программного продукта сторона, обращенная к пользователю, столь же важна, как и сторона, обращенная к машине.
Многие из нас бранили далекого безымянного автора за скудно документированную программу. И многие поэтому пытались на всю жизнь привить молодым программистам уважение к документации, преодолевающее лень и пресс графика работ. В целом нам это не удалось. Я думаю, мы использовали неверные методы.
Томас Дж. Уотсон Старший (Thomas J. Watson, Sr.) рассказал мне историю своего первого опыта в качестве продавца кассовых аппаратов в северной части штата Нью-Йорк. Исполненный энтузиазма, он отправился в путь в своем фургоне, нагруженном кассовыми аппаратами. Он прилежно объехал свой участок, но ничего не продал. Обескураженный, он сообщил об этом своему хозяину. Послушав некоторое время, управляющий сказал: «Помоги мне загрузить несколько касс в фургон, запрягай лошадь, и поедем снова.» Так они и сделали, и обходя покупателей одного за другим, старик показывал, как продавать кассовые аппараты. Судя по всему, урок пошел впрок.
Несколько лет я старательно читал группам инженеров-программистов лекции о необходимости и желательности хорошей документации, увещевая их все с большим пылом и красноречием. Это не подействовало. Я предположил, что они поняли, как правильно составлять документацию, но не делали этого по недостатку рвения. Тогда я попробовал погрузить в повозку несколько кассовых аппаратов, т.е. показать им, как делается эта работа. Это имело значительно больший успех. Поэтому оставшаяся часть этого повествования посвящена не столько поучениям, сколько объяснению того, как делать хорошую документацию.
Какая документация требуется?
Необходимы различные уровни документации: для пользователя, обращающегося к программе от случая к случаю, для пользователя, который существенно зависит от программы в своей работе, и для пользователя, который должен адаптировать программу к изменившемуся окружению или задачам.
Чтобы использовать программу. Каждому пользователю требуется словесное описание программы. По большей части документация страдает отсутствие общего обзора. Описаны деревья, прокомментированы кора и листья, но план леса
* Томас Дж. Уотсон Старший — основатель компании IBM (примеч.
отсутствует. Чтобы написать полезное текстовое описание, взгляните издалека, а затем медленно приближайтесь:
1. Назначение. Что является главной функцией программы и причиной ее написания?
2. Среда. На каких машинах, аппаратных конфигурациях и конфигурациях операционной системы будет она работать?
3. Область определения и область значений. Каковы допустимые значения входных данных? Какие правильные значения выходных результатов могут появиться?
4. Реализованные функции и использованные алгоритмы. Что конкретно может делать программа?
5. Форматы ввода-вывода, точные и полные.
6. Инструкция по работе, в том числе описание вывода на консоль и устройство вывода при нормальном и аварийном завершении.
7. Опции. Какой выбор предоставляется пользователю в отношении функций? Каким образом нужно его задавать?
8. Время работы. Сколько времени занимает решение задачи заданного размера на заданной конфигурации?
9. Точность и проверка. Какова ожидаемая точность результатов? Какие имеются средства проверки точности?
Часто все эти данные можно изложить на трех или четырех страницах. При этом нужно уделить особое внимание полноте и точности. Большую часть этого документа нужно вчерне написать до разработки программы, поскольку в нем воплощены основные плановые решения.
Чтобы доверять программе. Описание того, как использовать программу, нужно дополнить описанием того, как убедиться в ее работоспособности. Это означает наличие контрольных примеров.
Каждый экземпляр поставляемой программы должен содержать несколько небольших контрольных примеров, которые можно постоянно использовать, чтобы уверить пользователя в том, что он может доверять программе, и она правильно загружена в машину.
Кроме того, нужны более тщательные тесты, которые обычно выполняются только после модификации программы. Они относятся к трем участкам области входных данных:
1. Основные параметры, проверяющие главные функции программы на обычно встречаемых данных.
2. Примеры на грани допустимого, проверяющие границы области входных данных и убеждающие, что работают наибольшие значения, наименьшие значения и все допустимые исключения.
3. Примеры за границей допустимого, проверяющие границы с обратной стороны и убеждающие, что недопустимые значения вызывают правильные диагностические сообщения.
Чтобы модифицировать программу. Для адаптации или исправления программы требуется значительно больше данных. Разумеется, требуются все детали, а они содержатся в хорошо прокомментированном листинге. У пользователя, модифицирующего программу или редко ее использующего, возникает острая необходимость в ясном отчетливом обзоре, на этот раз внутренней структуры. В такой обзор входят:
1. Блок-схема или граф подпрограммной организации. Подробнее об этом см. ниже.
2. Полные описания используемых алгоритмов или ссылки на такие описания в литературе.