Мифический человеко-месяц

      Важнейшим моментом, жизненно важным для решения проблемы программирования без ошибок, является стремление рассматривать элементы управления в си-, стемо как управляющие структуры, а не как отдельные операторы перехода. Этот образ мысли является важным шагом вперед.
      Автономная отладка
      За последние двадцать лет процедуры отладки программ развивались по большому циклу, и в некотором смысле они сегодня вернулись туда, откуда начинали. Этот цикл прошел четыре этапа. Любопытно проследить за ними и обнаружить предпосылки каждого шага.
      Машинная отладка. Первые ЭВМ имели сравнительно плохое внешнее оборудование и очень медленный ввод/вывод. Обычно машина считывала с бумажных или магнитных лент и на них же помещала результаты, а для подготовки лент и печати на них использовались автономные устройства. Они делали ввод и вывод с лент очень неудобными для отладки, поэтому вместо них стали использоваться пульты. Таким образом, отладка была организована так, что в течение одного выхода на машину имелась возможность пропустить отлаживаемую программу столько раз, сколько это удастся.
      Программист тщательно разрабатывал процедуру отладки, планировал, где остановиться, какие ячейки памяти проверить, что следует ожидать там и что делать, если ожидания не оправдались. Эта неприятная необходимость программировать самого себя в качестве отладочной машины занимала почти половину времени, затрачиваемого па написание отлаживаемой машиной программы.
      Самым страшным грехом считалось тогда нажатие па кнопку ПУСК без предварительного разбиения программы на части с планируемыми остановами.
      Выдача памяти. Машинная отладка была очень эффективна: при выходе на машину, длившемся два часа, можно было получить до дюжины выдач. Но вычислен-тельных машин было мало, они были очень дорогие, и одна мысль о том, что почти все машинное время тратится впустую, приводила в ужас.
      Поэтому с появлением быстродействующих печатающих устройств методика отладки изменилась. Программа пропускалась до тех пор, пока не появлялась Выборочная выдача. Машины, в которых при-менялась выдача памяти, имели сначала 2000-4000 слов, или от 8 до 16 тыс. байтов памяти. Но размеры памяти стремительно росли, и вскоре производить выдачу всей памяти стало непрактично. Поэтому появились методы для выборочной выдачи, для избирательной трассировки и для вставки в программу команд выдачи. Test ran в OS/360 может считаться последним словом в этом направлении; он позволяет вводить в программу команды выдачи без повторного ассемблирования пли рекомпиляции.
      Диалоговая отладка. В 1959 г. Кодд со своими коллегами3) и Стрейчи6) независимо опубликовали работы, посвященные отладке в режиме разделения времени, методу, позволяющему сочетать преимущества быстрой оборачиваемости в случае машинной отладки и эффективного использования машины при отладке " в пакетном режиме.
      В обеих системах в памяти вычислительной машины хранилось несколько программ, готовых к выполнению. Каждая отлаживаемая программа имела в своем распоряжении программно-управляемый терминал. Управляла отладкой программа-супервизор. Когда программист за терминалом останавливал свою программу, чтобы посмотреть результаты или внести исправления, супервизор пропускал другую программу, так что машина постоянно оставалась занятой.
      Мультипрограммная система Кодда была создана, но основное внимание ее разработчики направили на увеличение производительности путем улучшения эффективности ввода/вывода, и диалоговая отладка в ней не была реализована. Идеи Стрейчи были усовершенствованы Корбато п его коллегами и реализованы в 1963 г. на экспериментальной системе для IBM 7090 в MIT7). Эта разработка непосредственно привела к проектам Multics, TSS и другим сегодняшним системам разделения времени.
      С точки зрения пользователя основные различия между традиционной машинной отладкой и современной диалоговой отладкой сводятся к средствам, ставшим возможными благодаря появлению программы-супервизора и связанных с нею языковых интерпретаторов. Теперь можно писать программы и отлаживать их на языке высокого уровня. Эффективные средства редактирования упростили проблему внесения изменений и получения выборочных выдач памяти.
      Возврат к возможностям быстрой оборачиваемости, присущим машинной отладке, не означал, однако, возврата к предварительному планированию отладки. В определенном смысле такое предварительное планирование уже не столь необходимо, как раньше, потому что машинное время не тратится впустую, пока программист сидит и размышляет.
      Тем не менее, известны интересные экспериментальные данные Гоулда8), показывающие, что при диалоговой отладке наиболее успешным бывает первый диалог 'каждого сеанса. Это позволяет с уверенностью утверждать, что мы не реализуем всех потенциальных возможностей диалога именно из-за отсутствия плана отладки. Настало время вернуть к жизни старые методы машинной отладки.
      Я считаю, что плодотворное использование хорошей терминальной системы требует, чтобы работе за столом посвящалось, как минимум, два часа после каждого двухчасового сеанса за терминалом. Половина этого времени обычно уходит на обработку последнего сеанса: на ведение личного журнала отладки, на занесение новых распечаток программы в личную тетрадь, на объяснение странных явлений. Вторая половина посвящается подготовке: планированию изменений и усовершенствований, разработке подробных тестов на следующий раз. Без такого предварительного планирования трудно производительно работать все два часа сеанса. А без "домашнего анализа" трудно обеспечить систематическое движение вперед от одного сеанса к другому.
      Тесты. Что касается разработки реальных процедур отладки и тестов, то все это очень хорошо изложено в работе Груенбергера9), хотя есть и менее подробные изложения в некоторых других учебниках 10'11).
      Системная отладка
      Системная отладка неожиданно оказалась очень трудной частью процесса создания системы программирования. Я уже рассматривал некоторые причины как сложности этой проблемы, так и ее непредвиденности. Из всего сказанного необходимо усвоить две вещи: отладка системы будет длиться дольше, чем это ожидается, и ее трудность можно преодолеть посредством крайне систематичного и планируемого подхода. Давайте посмотрим, в чем заключается этот подход12).
      Использование отлаженных компонент. Если не общепринятая практика, то здравый смысл требуют, чтобы отладка системы начиналась только после того, как начали работать ее части.
      Обычная практика отступает от этого принципа по двум направлениям. Первый подход гласит: "свяжите все это вместе и опробуйте". Он основывается на идее о том, что в дополнение к ошибкам в компонентах появятся ошибки в системе (т. е. в сопряжениях). И чем раньше все части будут связаны воедино, тем раньше выявятся системные ошибки. Более примитивная идея сводится к тому, что, используя отдельные части системы для проверки друг друга, можно сэкономить на подготовке тестов. Все это так, однако опыт показывает, что не совсем так,-использование готовых, отлаженных компонент экономит вполне достаточно времени на системной отладке, чтобы использовать его на подготовку тестов и на тщательную отладку компонент.
      Несколько более смутная идея "известных ошибок" сводится к тому, что можно начинать комплексную отладку системы уже после того, как в компонентах найдены все ошибки, но прежде, чем они будут исправивлены. Тогда, согласно этой теории, при отладке системы все ожидаемые эффекты таких ошибок уже известны, так что их можно проигнорировать, сосредоточить внимание на новых явлениях.
      Но ато лишь иллюзия, попытка обосновать отставание от графика. Никто не может предвидеть всех эффектов, вызываемых уже известными ошибками. Если бы эта связь была столь непосредственной, отладка системы не была бы таким трудным делом. Более того, исправление известных ошибок обязательно приведет к появлению новых, и тогда отладка системы совершенно запутается.
      Оснастка. Под "оснасткой" я понимаю все программы и данные, подготавливаемые для проведения отладки, но никогда не появляющиеся в конечном продукте. Нет ничего страшного, если объем таких программ примерно равен половине объема всей системы.
      Один из таких приемов - фиктивная компонента, которая включает в себя только сопряжения, и, может быть, какие-то придуманные данные пли несколько тестов. Например, в системе может быть программа сортировки, которая еще нс закончена. Тогда соседние программы можно отлаживать с использованием фиктивной программы, которая только читает и проверяет формат входных данных и выдает набор бессмысленных, но упорядоченных данных правильного формата.
      Второй прием - это мини-файл. Очень распространенной ошибкой является неправильное понимание форматов файлов на ленте ц на диске. Поэтому имеет смысл создавать маленькие файлы, содержащие только несколько типичных записей, но зато все описания, указатели и т. д.
      Предельным случаем мини-файла является фиктивный файл, которого в действительности вовсе нет. Язык управления задачами (ЯУЗА) в OS/360 обеспечивает такое средство, крайне полезное при отладке компонент.
      Еще одна сторона оснастки - это вспомогательные программы. Генераторы тестовых данных, специальные анализирующие распечатки, анализаторы таблиц перекрестных ссылок - все это примеры той специальной "арматуры", которую вы можете подготавливать по своему желанию 13).
      Контроль за изменениями. Строгий контроль во время испытаний - это один из наиболее впечатляющпх методов отладки оборудования, и он в равной мере необходим и в системах программного обеспечения.
      Прежде всего кто-то дол-кон быть ответственным. Этот кто-то, и только он один, должен давать разрешения на внесение изменении в компоненты или на замену одного варианта другим. Затем, как уже указывалось выше, следует иметь контрольные копии системы: одну неизменяемую копию последней версии, использованной для отладки компонент; одну проверяемую копию, в которую вносят исправления; для каждого программиста - копии, с которыми он может работать в своей части системы, исправляя ошибки или осуществляя расширения.
      В инженерных моделях Системы 360 среди обычной желтой проволоки вдруг оказывались ярко-красные внткп. Дело в том, что когда обнаруживалась ошибка, инженеры делали две вещи. Быстро придумывался способ ое исправления, который и вносился в систему с тем, чтобы проверка могла продолжаться. Это исправление делалось красной проволокой и выделялось, как зияющая рана. Оно вносилось в журнал. Тем временем подготавливался официальный документ об изменениях и закладывался в мельницу автоматизации проектирования. Наконец, появлялись исправленные чертежи и монтажные схемы и новая панель с изменениями, реализованными в печатных схемах или желтой проволокой. Теперь физическая модель п ее описание опять соответствовали друг другу, и красная проволока убиралась.
      В программировании нужен свой метод красной проволоки, крайне необходим строгий контроль и глубокое уважение к бумаге, которая в конечном счете представляет собой основной продукт нашей деятельности. К жизненно важным составляющим этого метода относится внесение всех изменений в журнал и различие, четко проводимое в исходной программе, между поспешным "приклеиванием заплат" и тщательно продуманными, проверенными и документированными исправлениями.
      Не более одной компоненты за раз! Эта заповедь вполне очевидна, но оптимизм и леность заставляют нас пренебрегать ею. Чтобы ей следовать, нужны фиктивные программы и другие вспомогательные средства, а это требует дополнительного труда. И, в конце концов, может быть эта работа вовсе не нужна? Может быть, отпибок-то и пет?
      Но не поддавайтесь соблазну! Тщательная отладка системы сводится именно к этой заповеди. Предполагайте, что ошибок будет очень много, и планируйте последовательную процедуру их вылавливания.
      Отметим, что необходимо иметь хорошие тесты, проверяющие незаконченную систему после добавления к пей каждого нового куска, п старые, успешно работавшие в последнем неполном варианте части, которые следует перепроверять при каждом добавлении.
      Квантуйте изменения! Когда система уже начнет работать, разработчики отдельных компонент время от времени будут приносить новые, свеженькие версии своих компонент - работающие быстрее, меньшие по объему,, более полные или содержащие как будто меньше ошибок. Замена работающей компоненты новой версией требует той же самой систематической процедуры проверки, что и добавление повой компоненты, хотя это и займет меньше времени.
      Каждая бригада, разрабатывающая новый вариант своей компоненты, использует последнюю отлаженную версию объединенной системы как основание для отладки своего куска. Их работа усложнится, если это основание вдруг окажется шатким - начнет изменяться. Конечно, изменения необходимы, но их следует квантовать. Тогда в распоряжении каждого пользователя будут периоды продуктивной стабильности, прерываемые точками - внесением изменений в систему. Но. они гораздо менее разрушительны, чем постоянное встряхивание. Биледи и Леман н) утверждают очевидное: кванты должны быть очень большими и редкими во времени пли, напротив, очень маленькими и частыми. Последняя стратегия в соответствии с их моделью ближе к неустойчивости. Мой опыт подтверждает это:
      я никогда не рискнул бы применить эту стратегию на практике.
      Квантование изменений хорошо согласуется с методом красной проволоки. Поспешная заплата сохраняется до появления следующей по плану версии компоненты, в которой эта ошибка уже исправлена, а соответствующая документация оформлена должным образом. '
      XIV. ПРИБЛИЖЕНИЕ КАТАСТРОФЫ
      "Никто не любит вестника, приносящего плохие новости".
      (Софокл)
      - Как выходит, что проект опаздывает на год?
      - Постепенно.
      Когда становится известно, что проект безнадежно отстает от графика, многим кажется, что этой катастрофе предшествовал целый ряд крупных неудач. Чаще всего, однако, в беде повинны термиты, а не цунами, и отставание от графика происходило медленно, но верно. И действительно, с крупными неудачами легче справиться: мобилизуются все силы, осуществляются радикальные перемены, предлагаются новые подходы. Весь коллектив оказывается на высоте.
      Но ежедневное отставание от графика труднее распознать, труднее предотвратить труднее исправить. Вчера был болен нужный человек, и встреча не состоялась. Сегодня не работают машины, потому что молния повредила трансформатор и в здании нет электроэнергии. Завтра нельзя будет начать отладку программ на дисках, потому что диски прибудут с завода только через неделю. Снегопад, общественная работа, семенные неприятности, непредвиденная встреча с заказчиками, ревизия - список можно продолжать до бесконечности. Каждый откладывает часть своих дел не более чем на полдня, на день. Но день за днем отстаивание от графика все растет.
      Вехи или помехи?
      Как проследить за тем, чтобы большой проект укладывался в строгий график? Прежде всего нужно иметь сам график. Для каждого события, называемого вехой, устанавливается дата. Определение дат - это сложная проблема, она решающим образом зависит от опыта.
      Существует только одно разумное правило устанав-ления вех. Вехи должны быть конкретными, специфическими, датируемыми событиями, определенными строго и четко. Вот контрпримеры: уже по истечении половины всего времени, отведенного на программирование, видимо, можно утверждать, что оно "закончено на 90%"; почти с самого начала отладки кажется, что она "завершена на 99%"; "проектирование завершено* - это событие, о котором можно заявлять практически когда угодно').
      Конкретные же вехи - это стопроцентные события. "Спецификации подписаны архитекторами и разработчиками", "исходная программа написана, отперфо-рирована и записана на библиотечный диск", "отлаживаемая версия прошла все тесты". Эти конкретные вохп позволяют разграничивать неопределенные этапы проектирования, программирования и отладки.
      Гораздо важнее, чтобы вехи были четкими и недвусмысленными, нежели удобными для проверки со стороны начальства. Вряд ли человек станет вводить в заблуждение других, если перед ним стоят четкие вехи и он сам не обманывается относительно их достижения. Если же вехи определены неясно и расплывчато, то руководитель, принимая желаемое за действительное, часто сам воспринимает совсем не то, что до1-;ладывает ему подчиненный. Дополняя Софокла, скажем, что п приносить плохие известия никто не любит; поэтому говорящий невольно смягчает их, не имея никакого желания солгать.
      Два интересных исследования по оценке поведения исполнителей в больших проектах показали, что:
      1. Оценки длительности некоей работы, сделанные до начала этой работы, тщательно пересматриваемые в процессе подготовки каждые две недели, почти не меняются по мере приближения срока ее начала, независимо от того, насколько неверными они оказываются трех недель перед завершением по графику2).
      2. Во время работы переоценка ее длительности непрерывно уменьшается по мере продвижения к концу.
      3. Недооценка не изменяется сколько-нибудь значительно во время работы за исключением последних трех недель перед завершением по графику 2).
      Четко расставленные вехи - это большая услуга бригаде, и она вправе ожидать ее от руководителя. Смутные, неясные вехи - тяжкое наказание. Это помехи, они скрывают истинное положение вещей до тех пор, когда уже ничего нельзя исправить, они подрывают моральный дух коллектива. А хроническое отставание от графика разлагает коллектив окончательно.
      "Другие все равно опаздывают" Мы на день отстали от графика, ну и что? Кто станет волноваться из-за одного дня? Мы сделаем это дозже. И многое другое мы тоже откладываем на потом.
      Бейсболисты знают о существовании дара, не зависящего от физической силы человека. Это - настыр-ность. Ею непременно наделены великие игроки и великие команды. Это способность бегать быстрее, чем нужно, двигаться живее, чем нужно, быть упорнее, чем нужно. Такой дар необходим и большим коллективам программистов. Настырность означает умение найти дополнительные резервы, второе дыхание, позволяющее группе справиться с обычными неприятностями, предвидеть маленькие катастрофы и избежать их. Расчетливый ответ, размеренные усилия - это холодные компрессы, которые охлаждают пыл. Как мы уже видели, необходимо беспокоиться, даже если мы отстаем от графика всего на один день. Такие отставания накапливаются, приближая катастрофу.
      Но далеко не каждое отставание от графика должно служить поводом для беспокойства. Какой-то расчет в действиях руководителя должен быть, пусть даже это охлаждает пыл работника. Но как определить, чем чревата та или иная задержка? В этом деле незаменима схема PERT или метод критического пути. Он показывает, кому чего не хватает, и кто оказался на критическом пути, где любые задержки отодвигают сроки окончания всей работы. Кроме того, сетевой график показывает, до каких пор могут нарастать задержки, не приводя нас на критический путь.
      Метод PERT, строго говоря, является усложнением метода критического пути, где устанавливаются три отрезка времени для каждого события, соответствующие различным вероятностям выполнения их в установленные сроки. Я не считаю, что такое усовершенствование стоит дополнительных усилий, но для краткости я буду называть любой сетевой график с критическим путем схемой PERT.
      Подготовка схемы PERT - наиболее трудоемкий втап ее использования. Составление сетевого графика, установление зависимостей и определение этапов требуют очень больших затрат на планирование на самых ; ранних этапах проекта. Первая схема всегда ужасна, и немало изобретательности придется приложить, прежде чем получится вторая.
      В ходе выполнения проекта схема PERT разоблачает деморализующую отговорку: "Другие все равно опаздывают". Она показывает, как избежать критического пути и что делать, если задержка все-таки произошла.
      Сор в избе
      Когда младший руководитель замечает, что его маленькая группа отстала от графика, он далек от мысли сейчас же бежать к начальству с этим плохим известием. Может быть, группа сумеет поправить дела. Или он сам придумает что-нибудь, чтоб справиться с проблемой. Так зачем же беспокоить начальника? Младший руководитель для того и существует, чтобы справиться с такими проблемами. А у старшего руководителя без того достаточно забот, требующих его внимания и участия, так что сам он не ищет новых хлопот. И сор оставляют в избе, заметают под коврик.
      Но каждый старший руководитель нуждается в информации двух видов: о происшествиях, требующих его вмешательства, и о положении дел, сообщаемом для сведения3). Для этой цели ему нужно знать о положении во всех группах. Однако получить правдивую картину очень трудно.
      Именно здесь сталкиваются интересы старшего и младшего руководителей: младший опасается, что если он доложит о своих проблемах, то "начальство примет меры". А в случае его вмешательства младший руководитель не волен поступать по-своему, его власть уменьшается, нарушаются другие планы. Поэтому пока младший руководитель считает, что он может справиться сам, он не посвящает старшего в свои затруднения.
      В распоряжении старшего руководителя есть два метода, позволяющие обнаружить "сор в избе", и он должен использовать оба. Первы-й заключается в том,
      чтобы свести к минимуму конфликт между ролями п содействовать одинаковому взгляду па положение вещей. Второй метод рекомендует "заглядывать в углы".
      Сглаживание противоречий между ролями. Чтобы свести к минимуму конфликт между ролями, старший руководитель прежде всего должен различать информацию, требующую вмешательства, и информацию о положении дел. Он должен приучить себя никогда нс вмешиваться в дела, с которыми могут справиться сами подчиненные, и никогда не принимать никаких мор, в то время, когда он просто знакомится с положением дел. Я знавал одного руководителя, который неизменно поднимал трубку и начинал отдавать распоряжения, не дочитав до конца даже периого абзаца доклада, информировавшего о положении дел. Очевидно, что такая реакция руководителя лишает его возможности получить полную информацию.
      И, наоборот, когда младший руководитель знает, что его начальник воспримет доклад без паники или без попыток вмешательства, он склонен честно обрисовывать положение дел.
      Очень полезно все собрания, совещания, конференции разделять на чисто информационные и те, на которых принимаются решения, и строго придерживаться этого разделения. Конечно, начальник может принимать решения и сразу после информационного совещания, если он считает, что дело нс терпит отлагательств. Но каждый, по крайней мере, должен знать, чем это вызвано, а старший руководитель обязан дважды подумать, прежде чем сделать это.
      Как заглянуть в углы. Тем не менее начальник должен иметь в своем распоряжении методы, позволяющие узнать истинное положение дел, неважно с помощью ли руководителей низшего ранга пли же самостоятельно. Схема PERT и ее частые, строго расставленные вехи являются основным источником такой информации.
      Отчет, показывающий как вехи, так и реальное положение дел, является ключевым документом. В табл. 14.1 представлен отрывок из такого отчета. Этот отчет указывает на некоторые затруднения. Спецификации на несколько компонент не утверждены в срок. Внешняя документация (руководства) тоже не утверждена, и автономные испытания (альфа-тест) продукта не закончены.
      Такой отчет служит темой собрания, назначенного на 1 февраля. Вопросы для обсуждения известны всем, и руководитель группы, отвечающий за данную подсистему, должен быть готов объяснить причину опоздания, сказать, когда все будет закопчено, какие меры приняты, и, если нужна помощь со стороны руководства проекта или параллельных групп, указать, какая именно.
      В. Выссотски из фирмы Bell Telephone Laboratories принадлежит следующее замечание: "Я обнаружил, что в качестве вех выполнения проекта полезно указывать как "назначенные", так и "ожидаемые" даты. Назначенные даты принадлежат руководителю проекта и представляют собой план последовательного выполнения проекта как единого целого, который априори рассматривается как вполне обоснованный и выполнимый. Ожидаемые даты принадлежат младшему руководителю, в чьей компетенции находится данная часть проекта, и представляют собой его точку зрения на то, когда работа будет завершена при наличии необходимых ресурсов. Ожидаемые даты не касаются руководителя проекта, он должен в основном заботиться о получении вовсе не приятных, оптимистических, пусть даже самозащитных, заниженных, а точных и беспристрастных оценок. Как только это будет осознано, руководителе проекта сможет ясно увидеть те направления, где он встретится с затруднениями, если не предпримет чего-нибудь заранее"4).
      Подготовка схемы PERT входит в функции начальника и руководителей, отчитывающихся перед ним. Ее просмотр и. проверка, подготовка отчетов составляют круг обязанностей небольшой (1-3 человека) штатной группы, работающей непосредственно под эгидой старшего руководителя. Значение такой группы планирования и контроля трудно переоценить. В ее полномочия входит право выяснить у всех руководителей подразделений, когда они будут устанавливать или изменять вехи, и были ли нужные вехи достигнуты. Так как группа планирования и контроля берет на себя всю бумажную работу, то деятельность руководителей замыкается на главном - принятии решений.
      У нас была группа планирования н контроля, проявившая большое мастерство, энтузиазм и дипломатическое искусство. Ею руководил А. М. Пьетрасанта, который проявил недюжинные способности в разработке эффективных, но ненавязчивых методов контроля. В результате отношение к его группе было в высшей степени уважительным и терпимым. Для группы, имеющей такие раздражающие обязанности, это настоящее достижение.
      Скромные затраты на обеспечение функции планирования и контроля себя вполне оправдывают. Такая группа делает для выполнения проекта гораздо больше, чем если бы все эти люди были непосредственно заняты написанием программ, потому что группа планирования и контроля всегда на страже, она делает видимыми самые незначительные задержки, выявляет критические обстоятельства. Это система раннего предупреждения, предотвращающая постепенную потерто года.
      XV. ВТОРОЕ ЛИЦО
      "Mы не обладаем тем, чего не понимаем".
      (Гете)
      "О, дайте мне талант комментатора, который, не углубляясь в суть явлений, будоражит умы людей".
      (Краббе)
      Программа - это сообщение, передаваемое человеком машине. Строго упорядоченный синтаксис, тщательные определения существуют для того, чтобы сделать наши намерения понятными бессловесной машине.
      По написанная программа имеет другое лицо, обращенное к человеку-пользователю, и оно должно уметь говорить. Даже самые личные программы должны обладать такой способностью, потому что память может подвести автора-пользователя, и ему может понадобиться восстановить детали того, что им написано.
      Как же необходима документация для производственной программы, пользователь которой удален от автора и во времени, и в пространстве! Второе лицо программного продукта, обращенное к пользователю, так же важно, как и то, что обращено к машине.
      Почти всем нам не раз приходилось втихомолку проклинать далекого и анонимного автора небрежно и скудно документированной программы. И почти все мы пытались поэтому воспитать в молодых программистах соответствующее отношение к документации, которое сохранялось бы всю жизнь, невзирая на леность и нехватку времени. Вообще говоря, нам это нс удалось. Я думаю, что мы пользовались неверными методами.
      Томас Дж. Уотсон-старший *) рассказывал как-то о своем первом опыте в качестве коммивояжера, продающего кассовые аппараты. Полный энтузиазма, он отправился в путь, погрузив кассовые аппараты в фургон. Он прилежно изъездил всю местность, но так и не продал ни одного аппарата. Совершенно подавленный неудачей, он доложил о пей хозяину. Тот выслушал отчет, а затем сказал: "Помогите мне погрузить аппараты в фургон, запрягите лошадь, и снова в путь". Так они в сделали, объехали одного покупателя аа другим, и старший показывал, как, продавать кассовые аппараты. Дальнейшее показало, что урок не пропал зря.
      В течение нескольких лет на лекциях по технологии программирования я прилежно убеждал своих студентов в необходимости хорошей документации и делал это еще более пылко и красноречиво, чем начинающий коммивояжер. Но это не сработало. Я считал, что они научились подготавливать соответствующую документацию, но не делают этого из-за отсутствия энтузиазма. И тогда я решил "погрузить пресловутые кассовые аппараты в фургон" - т. е. показать, как нужно делать работу. Такой подход оказался гораздо успешнее. Поэтому в дальнейшем изложении я откажусь от призывов и сосредоточусь на вопросе о том, как подготовить хорошую документацию.
      Какая документация нужна?
      Различные уровни документации требуются для случайного пользователя программы, для пользователя, который должен постоянно полагаться на программу, и для пользователя, который должен приспосабливать программу к изменению обстоятельств или целей.
      Для использования программы. Каждому пользователю нужно текстовое описание программы. Почти всегда документация не дает общего представления о программе. Описываются деревья, комментируются ветви и листья, но нет карты леса. Чтобы подготовить хороший текст, начинайте с самого начала и медленно двигайтесь вперед.
      1. Назначение. Какова основная функция программы, для чего она?
      2. Ситуация. На каких мшинах, в какой конфигурации и на какой операционной системе она будет работать?
      3. Область и сфера действия. Какова область входных данных? В каком диапазоне могут появиться выходные результаты?
      4. Реализуемые функции и используемые алгоритмы. Что именно она делает?
      5. Форматы ввода/вывода. Точные и полные.
      6. Рабочие процедуры, включая нормальное И аварийное окончание, описывают все, что видно с пульта и будет получено на выдачах.
      7. Варианты. Какие функции может выбирать пользователь? Как этот выбор определяется?
      8. Время исполнения. Сколько времени требует задача указанного объема при определенной конфигурации оборудования?