Страница 27 из 28
1. Блок-схема или граф подчиненности подпрограмм. Последнее предпочтительней. (Подробнее обсуждается ниже.)
2. Полные описания используемых алгоритмов или ссылки на соответствующие описания в литературе.
3. Форматы всех используемых файлов.
4. Схема передачи информации - последовательность считывания данных или программ с ленты или диска - и описание того, что происходит на каждом этапе передачи.
5. Обсуждение модификаций, допускаемых первоначальным проектом, сущность и расположение мест подключения и выходов из программ, свободное обсуждение идеи первого автора о возможных модификациях и о путях их осуществления. Полезны также его замечания относительно скрытых "ловушек".
Несостоятельность блок-схем
Блок-схемы - это та часть документации к программе, которая почти всегда имеется в избытке. Между тем многие программы вообще не нуждаются в блок-схемах и лишь очень немногие из них требуют больше одного листа таковых.
Блок-схемы показывают структуру ветвления программы только в одном ее аспекте. Но даже эта структура видна достаточно четко, только если вся блок-схема помещается на одной странице, и о ней очень трудно получить хорошее представление, если блок-схема располагается на нескольких листах, связанных вместе нумерованными стрелками.
Блок-схема, помещающаяся на одной странице, для большой программы по существу превращается в общий план программы, перечень ее основных этапов или блоков, и, как таковая, она очень удобна. На рис. 15.1 показан такой граф подчиненности подпрограмм.
Конечно, такой граф и не следует стандартам блок-схем, и пе нуждается в них. Все эти правила относительно вида элементов, стрелок, порядка нумерации и т. д. нужны только для того, чтобы можно было попять подробные блок-схемы.
Подробные блок-схемы, однако, устарели; они только мешают, и в лучшем случае пригодны для обучения повичков, еще не умеющих алгоритмически мыслить. В свое время предложенные Голдстайном и Нейманом ') маленькие квадратики на блок-схемах вместе со своим содержанием выступали в качестве языков высокого уровня, объединяя абсолютно непонятные операторы машинного языка в группы, имеющие определенный смысл. Как давно уже указал Айверсон2), в систематическом языке высокого уровня такая группировка уже осуществлена, так что каждый квадратик просто соответствует оператору (рис. 15.2). Тогда сами квадратики превращаются в случайное и ненужное упражнение по рисованию, и от них можно отказаться. Но теперь не остается ничего, кроме стрелок. Стрелки, соединяющие оператор со следующим за ним, не нужны, сотрем их. Остаются только операторы перехода. Но если следовать хорошей практике ,а использовать блочные структуры для минимизации числа операторов перехода, то останется совсем/немного стрелок, вот они-то очень сильно облегчают понимание. Эти стрелки можно перенести прямо ни распечатку программы и совсем избавиться от блок-схемы.
Рис. 15.2. Сравнение блок-схемы и соответствующей программы на PL/I.
В действительности блок-схемы гораздо больше превозносятся, чем используются на практике. Я никогда не видел, чтобы опытный программист чертил блок-схемы, прежде чем написать программу. Когда стандарты организации требуют блок-схем, то почти неизменно они рисуются после. Многие программистские организации с гордостью пользуются специальными программами для построения "этого незаменимого инструмента программиста" по готовой машинной программе. Я не считаю этот универсальный опыт прискорбным проявлением дурного топа, признание в котором сопровождается нервным смехом. Напротив, это свидетельство здравого смысла, урок, проливающий свет на истинную пользу блок-схем.
Апостол Петр так говорил о новообращенных язычниках и иудейских законах: "Что же вы желаете возложить на выи (их) иго, которого не могли понести ни отцы наши, ни мы?" (Деяние 15, 10). Я хотел бы сказать то же самое о начинающих программистах п устаревшей практике .использования блок-схем.
Самодокументированные программы
Основной принцип обработки данных учит нас, что безрассудно даже пытаться вести синхронную обработку независимых файлов. Гораздо лучше объединить их в один файл, где каждая запись содержит всю информацию из обоих файлов, относящуюся к данному ключу.
Однако наша практика ведения документации по программам не следует нашим же собственным теориям. Обычно нам приходится иметь программу в форме, удобочитаемой для машины, и одновременно независимую документацию, состоящую из текстовых описаний и блок-схем, удобочитаемых для человека.
Результаты подтверждают нашу теорию о непригодности раздельных файлов. Документация крайне плоха, а методы ее ведения и того хуже. Изменения, внесенные в программу, не находят быстрого, точного и устойчивого отображения на бумаге.
Решение проблемы, я считаю, в том, чтобы слить файлы,'чтобы ввести документацию в исходную программу. Вто одновременно и мощный побудительный стимул к соответствующему ведению документации, и гарантия' того, что эта документация всегда будет под рукой у пользователя программы. Такие программы называются самодокументированными.
Теперь очевидно, что введение блок-схем в такую программу - задача неприятная, хотя и возможная. Но стоит только признать, что блок-схемы устарели и нужно использовать язык высокого уровня, как появляется возможность объединения программы и документации.
Использование исходной программы в качестве носителя документации влечет за собой некоторые ограничения. С другой стороны, непосредственная, строка за строкой, доступность исходной программы читателю открывает возможности применения новых методов. Пришло время разработать радикально новые подходы и методы документирования программ.
В качестве основной задачи мы должны минимизировать затраты на документацию, тот груз, который ни мы, ни наши предшественники не могли успешно нести.
Подход. Первая идея заключается в том, чтобы те части программы, присутствие которых обусловлено самим языком программирования, играли роль документации. Так что метки, операторы и символические имена должны нести как нужно больше смысла.
Вторая идея сводится к использованию пространства и форматов выдачи для повышения читабельности программы и для представления структуры подчиненности и вложенности в программе.
Третья - это введение в программу необходимой Документации в качестве примечаний. Большинство программ содержит достаточно построчных примеча-вий; те из них, которые разрабатывались в организациях, имеющих жесткие стандарты "хорошей документации", часто содержат слишком много примечаний. Но даже в них, тем не менее, обычно не хватает примечаний, облегчающих их понимание и дающий представление обо всей программе.
Поскольку документация вставляется в структуры, имена и форматы программы, то почти все это следует делать, когда программа пишется в первый раХ, то есть тогда, когда она должна быть написана. Такой подход к документации сводит к минимуму дополнительную работу, к тому же этому почти ничто не препятствует.
Некоторые методы. Самодокументированная программа, написанная на PL/I, приведена на стр. 135- 137. Цифры в кружках не относятся к ней; это ме-тадокументация, используемая при обсуждении примера.
1. Используйте отдельное имя задачи при каждом запуске программы и ведите журнал запусков, где указывайте, что было опробовано, когда и с каким результатом. Если имя состоит из мнемонической части (здесь QLT) и числа (здесь 4), то это число можно использовать как номер запуска программы, связывающий вместе распечатки и журнал. При этом методе для каждого запуска нужна новая карта задачи, но их можно делать пакетом, дублируя общую информацию.
2. Введите в мнемоническое имя программы идентификатор версии, т. е. считайте, что будет несколько версий. Здесь индекс - это цифры года 1967.
3. Используйте текстовое описание в качестве комментариев к процедуре.
4. По мере возможности отсылайте к стандартной литературе, содержащей основные алгоритмы: Это экономит место, особенно если указывается более полное описание, чем можно было бы здесь привести, и позволяет осведомленному читателю пропустить то, что он знает.