|
|
Система автоматического документирования PL/SQL-кода (PLSQLDoc)
| Введение |
|
Длительный процесс разработки программной системы и последующего ее сопровождения не может обойтись без должного
документирования основных алгоритмов и реализаций бизнес-процессов. Сотрудники уходят, приходят новые и им необходимо
разбираться в унаследованном программном коде, понимать как он работает, по какой причине в данной строчке кода
располагается казалось бы не нужный вызов и т.п. Современный инструментарий программиста и по сей день не
позволяет формализовать семантику алгоритмов. На более высоком уровне абстракции мы успешно применяем
графические языки, подобные UML, однако, пояснение работы алгоритма или любого другого участка кода до сих
пор производится путем текстового изложения сути кода на естественном языке. У такого подхода имеются свои
минусы, но, по всей видимости, в ближайшее время он останется доминирующим. Опытные программисты использующие
современные языки программирования говорят о самодокументируемом коде. Однако в реальной жизни приходится
иметь дело как раз с неопытными программистами, мало заботящимися о простоте восприятия кода другими
участниками команды разработки. Приходится иметь дело с языками программирования, которые в силу различных
обстоятельств, запаздывают или останавливаются в собственном развитии, а резкий переход на новый мощный
язык зачастую чрезвычайно дорог, так как влечет за собой отказ от наработанного кода, переобучение персонала
и т.д.
|
|
Длительная разработка на одном из таких устаревших языков как PL/SQL побудила меня разработать
механизм автоматической генерации документации к программному коду на основе комментариев к различным объектам БД (
функциям, процедурам и методам пакетов) в формате XML, доступном для удобной трансформации, например, в HTML. Популярные
среды разработки на этом языке (PL/SQL Developer, Quest TOAD) не обладают подобной функциональностью. Основной задачей
автоматической генерации документации является выделить только значимую для ознакомления часть программного кода - названия
функций, комментарии к ним, описания формальных параметров и возвращаемых значений. Далее приводится пример
автоматической генерации программной документации к PL/SQL-пакету, реализующему механизм такой автогенерации.
|
| Архитектура |
|
Механизм генерации документации реализуется методами PL/SQL-пакета, осуществляющего сканирование
исходного кода функций, процедур, методов пакетов и выделение из кода комментариев оформленных в определенном стиле.
Комментарии к объектам БД представлены в XML-формате, что позволяет их достаточно просто преобразовать и отобразить
в требуемом виде, например, на внутреннем Web-сайте компании разработчика для внутренних нужд сотрудников или партнеров.
Поскольку программная документация формируется на лету, то вы получаете всегда самую свежую информацию о правилах
использования тех или иных программных интерфейсов.
|
| Спецификации |
Комментарий к пакету
<package name="PLSQLDOC" fullname="AUTODOC.PLSQLDOC">
<purpose><![CDATA[Реализация программного интерфейса автоматической генерации
документации к программным модулям на основе XML-комментариев.
]]>
</purpose>
<author><![CDATA[Савицкий Е.Н. ]]></author>
<date><![CDATA[19.12.2004 ]]></date>
</package>
|
|
Комментарий к методу пакета (функции или процедуре)
<method name="GETSCHEMAPACKAGES" fullname="AUTODOC.PLSQLDOC.GETSCHEMAPACKAGES">
<purpose>
<![CDATA[Формирует XML-описание списка пакетов заданой схемы.]]>
</purpose>
<author><![CDATA[Савицкий Е.Н. ]]></author>
<date><![CDATA[19.12.2004 ]]></date>
<returns>
<type>VARCHAR2</type>
<descr></descr>
</returns>
<param>
<name>a_user</name>
<type>varchar2</type>
<purpose><![CDATA[Наименование схемы, список пакетов,
содержащихся в которой, необходимо получить]]></purpose>
<default></default>
<dir>IN</dir>
</param>
</method>
|
| Пример использования |
|
В качестве примера использования описанного механизма приводится ASP-страница, выгружающая
комментарии ко всем пакетам схемы, а также ко всем методам пакетов. Исходный код страницы здесь не приводится, однако
содержится в архиве plsqlDoc.zip. Ниже приведен результат выполнения страницы:
|
| AUTODOC.PLSQLDOC -
Реализация программного интерфейса автоматической генерации
документации к программным модулям на основе XML-комментариев.
| | авторы: Савицкий Е.Н. [19.12.2004 ] | | | GETFUNCTIONCOMMENT -
Формирует XML-описание хранимой функции
| | Параметры: | | a_user varchar2 | IN | | | a_name varchar2 | IN | |
| | Возвращает: VARCHAR2, | | | GETPACKAGECOMMENT -
Формирует XML-описание пакета, которое содержит только комментарии к пакету
| | Параметры: | | a_user varchar2 | IN | | | a_name varchar2 | IN | |
| | Возвращает: VARCHAR2, | | | GETPACKAGEMETHODCOMMENT -
Формирует XML-описание заданного метода пакета.
| | Параметры: | | a_user varchar2 | IN | | | a_package varchar2 | IN | | | a_name varchar2 | IN | |
| | Возвращает: VARCHAR2, | | | GETPACKAGEMETHODS -
Формирует XML-описание списка методов указанного пакета.
| | Параметры: | | a_user varchar2 | IN | | | a_name varchar2 | IN | |
| | Возвращает: VARCHAR2, | | | GETPROCEDURECOMMENT -
Формирует XML-описание хранимой процедуры
| | Параметры: | | a_user varchar2 | IN | | | a_name varchar2 | IN | |
| | Возвращает: VARCHAR2, | | | GETSCHEMAPACKAGES -
Формирует XML-описание списка пакетов заданой схемы.
| | Параметры: | | | Возвращает: VARCHAR2, | |
|
|
|
|
|
