Фредерик Брукс - Мифический человеко-месяц или как создаются программные системы

У нас была умелая, энергичная и дипломатичная группа планирования и контроля, возглавлявшаяся А. М. Пьетрасанта (A. M. Pietrasanta), проявившим значительные изобретательные способности для разработки эффективных, но ненавязчивых методов контроля. В результате его группа пользовалась широким уважением и хорошим отношением. Это немалое достижение для группы, которая по природе своей должна вызывать раздражение.

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

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

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

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

Многие из нас бранили далекого безымянного автора за скудно документированную программу. И многие поэтому пытались на всю жизнь привить молодым программистам уважение к документации, преодолевающее лень и пресс графика работ. В целом нам это не удалось. Я думаю, мы использовали неверные методы.

Томас Дж. Уотсон Старший (Thomas J. Watson, Sr.) рассказал мне историю своего первого опыта в качестве продавца кассовых аппаратов в северной части штата Нью-Йорк. Исполненный энтузиазма, он отправился в путь в своем фургоне, нагруженном кассовыми аппаратами. Он прилежно объехал свой участок, но ничего не продал. Обескураженный, он сообщил об этом своему хозяину. Послушав некоторое время, управляющий сказал: «Помоги мне загрузить несколько касс в фургон, запрягай лошадь, и поедем снова.» Так они и сделали, и обходя покупателей одного за другим, старик показывал, как продавать кассовые аппараты. Судя по всему, урок пошел впрок.

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

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

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

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

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

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

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

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

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