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