Фредерик П. Брукс
| Вид материала | Документы |
| Глава 15. Обратная сторона Какая документация требуется? Чтобы доверять программе. Чтобы модифицировать программу. |
- Французский писатель, журналист и критик Фредерик Бегбедер, 1495.8kb.
- Фредерик Коплстон История философии. XX век Номер страницы указан в конце страницы, 2537.19kb.
- Gold Circle Films представляют фильм компании Integrated Films. О фильме история США, 1307.29kb.
- Брукс Кубик "Тренинг Динозавров. Забытые секреты силы и развития тела", 3174.72kb.
- 2. Во всем мире родоначальником научных основ организации производства признан: ◙ Фредерик, 992.99kb.
- Фредерик Бегбедер, 2049.29kb.
- Фредерик Бегбедер. 99 франков, 2045.96kb.
- Фредерик К. Хэтфилд всестороннее руководство по развитию силы , 4595.97kb.
- Фредерик Бегбедер. 99 Франков, 2399.26kb.
- Практикум по гештальттерапии петербург, 5899.47kb.
Глава 15. Обратная сторона
Чего мы не понимаем, тем не владеем.
ГЕТЕ
О, дайте мне выступить комментатором,
Скользящим по поверхности и будоражащим умы.
КРАББ
Компьютерная программа - это послание человека машине. Строговыстроенный синтаксис и тщательные определения нацелены на то, чтобыбездумной машине стали понятны намерения человека.
Но у написанной программы есть обратная сторона: она должна быть всостоянии рассказать о себе пользователю-человеку. Это требуется даже дляпрограммы, написанной исключительно для собственных нужд, поскольку памятьможет изменить автору-пользователю, и ему потребуется освежить детали своеготруда.
Насколько же более необходима документация для программы общегопользования, пользователь которой отдален от автора во времени, и впространстве! Для программного продукта сторона, обращенная к пользователю,столь же важна, как и сторона, обращенная к машине.
Многие из нас бранили далекого безымянного автора за скуднодокументированную программу. И многие поэтому пытались на всю жизнь привитьмолодым программистам уважение к документации, преодолевающее лень и прессграфика работ. В целом нам это не удалось. Я думаю, мы использовали неверныеметоды.
Томас Дж. Уотсон Старший* (Thomas J. Watson, Sr.) рассказал мне историюсвоего первого опыта в качестве продавца кассовых аппаратов в северной частиштата Нью-Йорк. Исполненный энтузиазма, он отправился в путь в своемфургоне, нагруженном кассовыми аппаратами. Он прилежно объехал свой участок,но ничего не продал. Обескураженный, он сообщил об этом своему хозяину.Послушав некоторое время, управляющий сказал: "Помоги мне загрузитьнесколько касс в фургон, запрягай лошадь, и поедем снова." Так они исделали, и обходя покупателей одного за другим, старик показывал, какпродавать кассовые аппараты. Судя по всему, урок пошел впрок.
Несколько лет я старательно читал группам инженеров-программистовлекции о необходимости и желательности хорошей документации, увещевая их всес большим пылом и красноречием. Это не подействовало. Я предположил, что онипоняли, как правильно составлять документацию, но не делали этого понедостатку рвения. Тогда я попробовал погрузить в повозку несколько кассовыхаппаратов, т.е. показать им, как делается эта работа. Это имело значительнобольший успех. Поэтому оставшаяся часть этого повествования посвящена нестолько поучениям, сколько объяснению того, как делать хорошую документацию.
Какая документация требуется?
Необходимы различные уровни документации: для пользователя,обращающегося к программе от случая к случаю, для пользователя, которыйсущественно зависит от программы в своей работе, и для пользователя, которыйдолжен адаптировать программу к изменившемуся окружению или задачам.
Чтобы использовать программу. Каждому пользователю требуется словесноеописание программы. По большей части документация страдает отсутствие общегообзора. Описаны деревья, прокомментированы кора и листья, но план леса *Томас Дж. Уотсон Старший - основатель компании IBM (примеч. перев.)отсутствует. Чтобы написать полезное текстовое описание, взгляните издалека,а затем медленно приближайтесь:
1. Назначение. Что является главной функцией программы и причиной еенаписания?
2. Среда. На каких машинах, аппаратных конфигурациях и конфигурацияхоперационной системы будет она работать?
3. Область определения и область значений. Каковы допустимые значениявходных данных? Какие правильные значения выходных результатов могутпоявиться?
4. Реализованные функции и использованные алгоритмы. Что конкретноможет делать программа?
5. Форматы ввода-вывода, точные и полные.
6. Инструкция по работе, в том числе описание вывода на консоль иустройство вывода при нормальном и аварийном завершении.
7. Опции. Какой выбор предоставляется пользователю в отношении функций?Каким образом нужно его задавать?
8. Время работы. Сколько времени занимает решение задачи заданногоразмера на заданной конфигурации?
9. Точность и проверка. Какова ожидаемая точность результатов? Какиеимеются средства проверки точности?
Часто все эти данные можно изложить на трех или четырех страницах. Приэтом нужно уделить особое внимание полноте и точности. Большую часть этогодокумента нужно вчерне написать до разработки программы, поскольку в немвоплощены основные плановые решения.
Чтобы доверять программе. Описание того, как использовать программу,нужно дополнить описанием того, как убедиться в ее работоспособности. Этоозначает наличие контрольных примеров.
Каждый экземпляр поставляемой программы должен содержать нескольконебольших контрольных примеров, которые можно постоянно использовать, чтобыуверить пользователя в том, что он может доверять программе, и она правильнозагружена в машину.
Кроме того, нужны более тщательные тесты, которые обычно выполняютсятолько после модификации программы. Они относятся к трем участкам областивходных данных:
1. Основные параметры, проверяющие главные функции программы на обычновстречаемых данных.
2. Примеры на грани допустимого, проверяющие границы области входныхданных и убеждающие, что работают наибольшие значения, наименьшие значения ивсе допустимые исключения.
3. Примеры за границей допустимого, проверяющие границы с обратнойстороны и убеждающие, что недопустимые значения вызывают правильныедиагностические сообщения.
Чтобы модифицировать программу. Для адаптации или исправления программытребуется значительно больше данных. Разумеется, требуются все детали, а онисодержатся в хорошо прокомментированном листинге. У пользователя,модифицирующего программу или редко ее использующего, возникает остраянеобходимость в ясном отчетливом обзоре, на этот раз внутренней структуры. Втакой обзор входят:
1. Блок-схема или граф подпрограммной организации. Подробнее об этомсм. ниже.
2. Полные описания используемых алгоритмов или ссылки на такие описанияв литературе.
3. Разъяснение структуры всех используемых файлов.
4. Обзор организации прохождения данных - последовательности, в которойданные или программы загружаются с ленты или диска и описание того, чтоделается на каждом ходе.
5. Обсуждение модификаций, предполагаемых исходным проектом, сущность ирасположение добавочных блоков и выходов и дискурсивное обсуждение мыслейавтора программы относительно изменений, которые могут оказатьсяжелательными, и как их можно провести. Полезно также изложить его замечанияо скрытых ловушках.