Самодокументированные программы

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

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

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

Решение проблемы, я считаю, в том, чтобы слить файлы,'чтобы ввести документацию в исходную программу. Вто одновременно и мощный побудительный стимул к \ соответствующему ведению документации, и гарантия' того, что эта документация всегда будет под рукой у пользователя программы. Такие программы называются самодокументированными.

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

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

В качестве основной задачи мы должны минимизировать затраты на документацию, тот груз, который ни мы, ни наши предшественники не могли успешно нести.

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

Вторая идея сводится к использованию пространства и форматов выдачи для повышения читабельности программы и для представления структуры подчиненности и вложенности в программе.

Третья — это введение в программу необходимой Документации в качестве примечаний. Большинство программ содержит достаточно построчных примеча-вий; те из них, которые разрабатывались в организациях, имеющих жесткие стандарты «хорошей документации», часто содержат слишком много примечаний. Но даже в них, тем не менее, обычно не хватает примечаний, облегчающих их понимание и дающий представление обо всей программе.

Поскольку документация вставляется в структуры, имена и форматы программы, то почти все это следует делать, когда программа пишется в первый раХ, то есть тогда, когда она должна быть написана. Такой подход к документации сводит к минимуму дополнительную работу, к тому же этому почти ничто не препятствует.

Некоторые методы. Самодокументированная программа, написанная на PL/I, приведена на стр. 135— 137. Цифры в кружках не относятся к ней; это — ме-тадокументация, используемая при обсуждении примера.

1. Используйте отдельное имя задачи при каждом запуске программы и ведите журнал запусков, где указывайте, что было опробовано, когда и с каким результатом. Если имя состоит из мнемонической части (здесь QLT) и числа (здесь 4), то это число можно использовать как номер запуска программы, связывающий вместе распечатки и журнал. При этом методе для каждого запуска нужна новая карта задачи, но их можно делать пакетом, дублируя общую информацию.

2. Введите в мнемоническое имя программы идентификатор версии, т. е. считайте, что будет несколько версий. Здесь индекс — это цифры года 1967.

3. Используйте текстовое описание в качестве комментариев к процедуре.

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

5. Укажите связь с книжным алгоритмом: а) изменения, б) специализации, в) представления.

6. Опишите все переменные. Используйте мнемонические имена. Используйте комментарии, чтобы превратить DECLARE в полную легенду. Отметьте, что такая легенда уже содержит имена и структурные описания, необходимо только описать, для чего они предназначены. Поступая таким образом, можно избежать повторения имен и структурных описаний.

7. Выделите инициализацию с помощью метки. /

8. Сгруппируйте операторы с помощью меток, чтобы показать их соответствие операторам в описании алгоритма в литературе.

9. Используйте абзацы и отступы для представления структуры и логической группировки- /

10. Вручную проведите в распечатке стрелки логических переходов. Они очень полезны при отладке и внесении изменений. Стрелки можно провести справа на полях и сделать их частью текста, /доступного машине.

11. Используйте построчные примечания или помечайте все, что не очевидно. Если используются способы, предлагаемые выше, то примечания будут короче и их будет меньше, чем обычно.

12. Располагайте, несколько операторов на одной строке или один оператор на нескольких строчках, чтобы подчеркнуть смысловую связь или обеспечить соответствие другому описанию алгоритма.

Почему бы и нет? Каковы недостатки такого подхода к документации? Их несколько, они были вполне реальны, но с течением времени превратились в воображаемые.

Наиболее серьезное возражение заключается в том, что увеличивается размер исходной программы, которую нужно хранить в памяти. Поскольку дело идет к тому, что мы будем хранить исходную программу в памяти, вводя ее непосредственно с терминала, это соображение становится все более важным. Я сам поймал себя на том, что мои комментарии к программе. написанной на APL и хранимой на дисках, всегда короче, чем когда я пишу на PL/I и собираюсь хранить все примечания на перфокартах.

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

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

В \какой степени все вышеуказанное применимо к программам на языке ассемблера? Я считаю, что основные идеи самодокументирования вполне приемлемы и здесь. Форматы и расположения программы менее свободны, поэтому их нельзя использовать столь гибко. Однако имена и структурные описания могут использоваться аналогичным образом, а широкое применение комментариев — это хорошая практика в любом языке.

Метод самодокументирования вызван к жизни использованием языков высокого уровня, и потому он демонстрирует наибольшую эффективность и максимально оправдывает себя именно в языках высокого уровня, используемых в системах прямого доступа, как пакетных, так и диалоговых. Как я уже доказывал, такие языки и системы оказывают огромную п'о-мощь программисту. Поскольку машины созданы для людей, а не люди для машин, то использование машины имеет как экономический, так и гуманистический смысл.

ЭПИЛОГ

Асфальтовая топь технологии программирования останется непроходимой еще очень долго. Никто не сомневается в том, что человечество будет продолжать попытки ее покорения как вслед за нашими достижениями, так и независимо от них. Системы программного обеспечения представляют собой, может быть, самые запутанные и сложные творения рук человеческих. Руководство этим сложным ремеслом потребует от нас умения наилучшим образом использовать новые языки и системы, наиболее эффективно приме-менять все известные методы технического руководства, а также здравого смысла и умения признавать наши слабости и просчеты.

ПРИМЕЧАНИЯ И ССЫЛКИ

I

1. А. И. Ершов считает, что это обстоятельство определяет не только трудные, но и радостные моменты ремесла программиста. Ershov A. P. Aesthetics and teh human factor in programming.— CACM, July 1972, 15, 7, 501—505. (Ершов А. П.. Эстетический и человеческий факторы в программировании.— Кибернетика, 1972, № 5.)

II

1. По оценкам В. А. Выссотски из фирмы: Bell-Telephone Laboratories, прирост рабочей силы в большом программистском проекте допускается на 30% в год. Больший рост числа сотрудников затрудняет и даже препятствует созданию важнейшей неформальной структуры и установлению связей в проекте, что обсуждается в гл. VII.

Ф. Д;к. Корбато из Массачусоттского Технологического института утверждает, что в большом проекте следует предвидеть текучесть кадров в пределах 20% в год, и заранее предусмотреть необходимость подготовки новичков и ввода их в формальную структуру проекта.

2. Ч. Портман из фирмы International Computers Limited утверждает: «Когда кажется, что уже все работает, все объединено в систему — вам еще осталось работы на четыре месяца». Некоторые графики распределения работ приводятся в статье Wolverion И. W. The cost of developing largescale software: — IEEE Trans. on Computers, June 1974, С—23, 6, р. 615—636.

3. Рисунками 2.5—2,8 мы обязаны Джерри Огдену, который, цитируя мой пример по первой публикации этой главы, значительно улучшил его оформление". Ogdin J. L. The Mongolian hordes versus superprogrammer.— Infosystems, December, 1972, p. 20—23.

Ill

1. Sackman H., Erikson W. J., Grant E. E. Exploratory experimental studies comparing online and offline programming performance.—CACM, January, 1968, 11, 1, 3—11.

2. Mills H. Chief programmer teams, principles, and procedures,—IBM Federal Systems Division Report FSC 71—5108, Gai-thersburg, Md., 1971V"⁹'"

[1] Номера сносок указывают на примечания автора, собранные в конце книги. {Прим. ред.}

* Следует, однако, признать, что авторская оценка относительной престижности производственной и административной работы не является универсальной. {Прим, ред.)

⇐ Предыдущая12131415161718192021

Поделиться: