Чтение онлайн

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

При наличии обширных комментариев инструментальные средства, подобные JavaDoc [URL 7] и DOC++ [URL 21], могут извлекать и форматировать их для автоматического создания документации на уровне API. Это является одним из конкретных примеров более универсальной методики, которой мы пользуемся, – исполняемые документы.

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

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

Если документ хранится в виде простого текста вместе с командами описания документов (например, в виде HTML, LATeX. или troff), то в этом случае можно использовать такие инструментальные средства, как Perl, для извлечения схемы и ее автоматического переформатирования. Если документ хранится в двоичном формате текстового процессора, то ознакомьтесь с некоторыми вариантами действий, приведенных во врезке, данной ниже.

Теперь документ – неотъемлемая часть разработки проекта. Единственным способом изменения схемы является изменение документа. Вы гарантируете, что спецификация, схема и программа находятся в согласии. Вы сводите к минимум работу, которую необходимо выполнить для внесения каждого изменения, и можете обновлять визуальные представления изменений автоматически.

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

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

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

Аналогичным образом можно генерировать документацию на уровне API из исходного текста программы, пользуясь инструментальными средствами, такими как JavaDoc и DOC++. Моделью является исходный текст программы: компилироваться может одно визуальное представление модели; другие представления предназначены для вывода на печать или просмотра на web-странице. Наша цель – работа над моделью (неважно, является ли эта модель самой программой или же каким-либо иным документом), и мы должны добиться того, чтобы все эти представления обновлялись автоматически (см. "Вездесущая автоматизация").

Внезапно документация оказывается не столь уж плохой.

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

Это является ошибкой. То, что программисты не составляют такие документы, вовсе не означает, что мы можем поступиться прагматическими принципами. Мы хотим, чтобы писатели восприняли те же основные принципы, что и прагматики, – соблюдали принципы DRY, ортогональности, а также концепцию "модель-визуальное представление", применяли автоматизацию и сценарии.

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

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