Использование гипертекста при документировании программ
Этот метод гораздо чаще применяется на практике по сравнению с предыдущим. Предыдущий метод ориентирован на то, что сгенерированное описание пользователь будет читать последовательно, раздел за разделом. Целью описываемого метода является создание не только печатного документа, а также предоставление программисту дополнительных возможностей при чтении кода с экрана. К ним можно отнести выборочный просмотр фрагментов кода, переход по ссылкам в графе потока управления и многие другие. Иначе говоря создатели этого метода поставили перед собой цель предоставить программисту возможность просматривать текст программы как гипертекстовый документ.
Рассмотрим теперь более подробно конструкции, используемые в гипертекстовых документах. С их помощью в документ вставлять таблицы, формулы, картинки и другие элементы. Рассмотрим некоторые из них более подробно.
Скрытие подробностей при описании фрагмента текста (folding)
При использовании данной конструкции на экране вместо соответствующего фрагмента текста отображается другой (обычно более короткий) текст, характеризующий содержимое данного фрагмента (Рис. 2 .7). Это используется для оформления комментариев и скрытия подробностей реализации.
В первом случае вместо некоторого фрагмента кода отображается его краткое описание. По желанию пользователя этот фрагмент кода может быть полностью отображен та экране. Это оказывается полезным когда фрагмент кода можно очевидным образом описать в двух словах, избавив тем самым программиста от необходимости просматривать весь фрагмент целиком.
Рис. 2.7 - Использование конструкции folding для скрытия подробностей реализации.
Во втором же случае для определенной языковой конструкции на экран может быть выведен комментарий, содержащий пояснения в виде текста и картинок. Даже если необходимо узнать, например, описание прототипа функции это избавляет от необходимости открывать заголовочный файл, не говоря уже о том, что из комментария можно получить и более подробную информацию.
Рис. 2.8 - Использование конструкции folding для оформления комментариев.
Переход по ссылкам (linking)
Эта конструкция позволяет осуществлять переход по ссылкам. Это значительно облегчает работу со связанными участками кода.
Рис.
2.9
- Переход между
связанными участками кода
при
помощи конструкции linking.
Данный метод документирования достаточно удобен и широко применяется на практике. Причина популярности этого метода заключается в том, что он позволяет документировать уже существующие исходные тексты программ и в том или ином виде поддерживается многими редакторами исходных текстов. В большинстве случаев добавление гипертекстовых элементов в документ происходит автоматически и не требует от программиста никаких усилий.
Представление исходного текста программ в форме книги
Прежде, чем описывать следующий метод, попробуем ответить на следующий вопрос: актуально ли сейчас использование исходных текстов программ в напечатанном виде? Опросы, проведенные среди программистов показывают, что это действительно так. Такая необходимость обычно возникает в следующих случаях:
при внесении в код большого числа изменений;
когда фрагмент кода не помещается на экране;
при работе с программой, с которой разработчик не сталкивался раньше;
при использовании заголовочных файлов в напечатанном виде для ссылок;
в случаях, кода изменения, вносимые в код настолько взаимосвязаны, что становится необходимо делать примечания о внесении каждого изменения;
для работы со сложными, запутанными языковыми конструкциями;
при объяснении кода другим людям (например при проведении инспекций кода);
при работе с кодом вне офиса;
при разборе плохо структурированных программ;
при разборе глобальных взаимодействий.
Теперь попытаемся выяснить следующее: как именно должен быть отформатирован документ, чтобы обеспечить пользователю максимальное удобство чтения? Прежде всего, такое форматирование должно обеспечивать быстры доступ к любому участку кода, текст программы должен быть хорошо структурирован, в нем должны быть выделены важные места. Помимо этого, код должен оставаться легким в использовании и быть совместимым с существующими программными средствами. Всем этим условиям удовлетворяет давно известный способ форматирования документа, а именно - книга.
Идея состоит в том, чтобы не нарушая целостность кода и сохраняя программу в работоспособном виде, отформатировать код так, чтобы текст программы стал похож на содержимое книги. Можно провести множество параллелей между содержимым книги и содержимым отформатированного таким образом документа. Так, например, оглавлению будет соответствовать структурированный список компонентов программы, индексу и нумерации страниц - ссылки на соответствующие номера строк, а главам, разделам, параграфам и предложениям - соответственно программные модули, секции внутри модуля (как, например, разделы Const, Type и Var), структурные языковые конструкции (например Case или While) и, наконец, простые языковые конструкции и объявления переменных.
Форматирование же самого текста программы заключается в приведении кода в более удобную для чтения форму. А именно: