Программная документация
При сопровождении программных продуктов наиболее часто возникающей задачей является анализ исходного кода. На это уходит от 50% до 90% времени, затрачиваемого на сопровождение. При этом эта процедура значительно упрощается, если исходные тексты программы так или иначе документированы.
Как показывает опыт, простого комментирования исходного текста бывает более чем недостаточно. Тем более что качественные комментарии можно встретить далеко не в каждой программе. В случае, когда исходный код сопровожден подробной документацией ситуация усложняется тем, что объем материала, в котором программисту придется разбираться возрастает во много раз. Существуют различные подходы к документированию программ, которые позволяют решить эту проблему для некоторых частных случаев.
Концепция "Literate Programming"
С появлением концепции структурного программирования в области сопровождения программ наступило некоторое улучшение, но, тем не менее, результаты все еще оставались не удовлетворительными. В связи с этим, Дональдом Кнутом была предложена концепция "Literate Programming". В 1984 году в журнале "Computer" он опубликовал статью "Literate Programming", в которой описал новый способ документирования программ и реализующую этот способ систему WEB.
Основная идея была в том, чтобы рассматривать программу не как последовательность инструкций для компьютера, а как литературное произведение (отсюда и название). Таким образом, программист при написании программы формально описывает действия, которые он ожидает от компьютера, вставляя в соответствующе места код на языке программирования. В результате получается целостное литературное произведение (например статья), которое одновременно является работающей программой.
В качестве реализации указанной концепции, Кнутом была предложена система WEB. В этой системе используются два языка: язык форматирования текста и язык программирования. Изначально в качестве языка форматирования текста использовался TeX, а в качестве языка программирования - PASCAL. В дальнейшем были выпущены версии с поддержкой других языков программирования и мультиязычные версии.
В системе поддерживаются две операции: WEAVE и TANGLE. Результатом выполнения операции WEAVE является документ TeX, а в при выполнении операции TANGLE генерируется текст на языке PASCAL. Подробнее это изображено на
Рис. 2.6 - Основные операции системы WEB.
Система WEB изначально создавалась как система, поддерживающая концепцию структурного программирования. Сгенерированный WEB документ состоит из параграфов, каждый из которых помимо текста может содержать код, в котором, в свою очередь, могут быть использованы ссылки на участки кода из других параграфов. Описание WEB - программы строится по принципу последовательного улучшения: определенный ранее параграф в дальнейшем можно доопределить при помощи операции '+='. Также система генерирует оглавление и индекс. В качестве комментариев используется текст, заключенный в двойные прямые скобки '[[...]]'. После описания каждого фрагмента кода, указываются номера параграфов, где этот код используется, а также номера параграфов, внутри которых соответствующий фрагмент кода доопределяется.
Как уже можно было заметить, этот метод документирования является несколько специфичным. Он практически идеально подходит для написания научных статей, но в силу ряда причин, его применение в остальных случаях затруднено. Основным неудобством является то, что сгенерированный в результате текст очень сложен для чтения и в случае, если WEB - описание будет утеряно, в программе будет очень сложно разобраться.