Средство автоматической документации short использует утверждения, как важную компоненту при извлечении из класса информации, значимой для потенциальных клиентов. Краткая форма класса - его описание на более высоком уровне. Она включает только ту информацию, которая полезна авторам клиентских классов, ничего не показывая из скрытых компонент, и не раскрывая реализации открытых. Но краткая форма сохраняет утверждения, составляющие основу документации, устанавливая контракты, которые класс предлагает своим клиентам.
Вот пример краткой формы класса
indexing
description: 'Стеки: Структуры с политикой доступа Last-In, First-Out %
%Первый пришел - Последний ушел, с фиксированной емкостью'
class interface STACK4 [G] creation
make
feature -- Initialization (Инициализация)
make (n: INTEGER) is
-- Создать стек, содержащий максимум n элементов
require
non_negative_capacity: n >= 0
ensure
capacity_set: capacity = n
end
feature -- Access (Доступ)
capacity: INTEGER
-- Максимальное число элементов стека
count: INTEGER
-- Число элементов стека
item: G is
-- Элемент в вершине стека
require
not_empty: not empty -- i.e. count > 0
end
feature -- Status report (Отчет о статусе)
empty: BOOLEAN is
-- Пуст ли стек?
ensure
empty_definition: Result = (count = 0)
end
full: BOOLEAN is
-- Заполнен ли стек?
ensure
full_definition: Result = (count = capacity)
end
feature -- Element change (Изменение элементов)
put (x: G) is
-- Втолкнуть x в вершину стека
require
not_full: not full
ensure
not_empty: not empty
added_to_top: item = x
one_more_item: count = old count + 1
end
remove is
-- Удалить элемент вершины стека
require
not_empty: not empty -- i.e. count > 0
ensure
not_full: not full
one_fewer: count = old count - 1
end
invariant
count_non_negative: 0 <= count
count_bounded: count <= capacity
empty_if_no_elements: empty = (count = 0)
end
Эта краткая форма не является синтаксически правильным текстом класса, посему здесь используется термин class interface вместо обычного термина class. Хотя достаточно просто превратить эту форму в правильный отложенный класс, известное понятие, рассматриваемое в деталях при изучении наследования.
| В среде ISE получить краткую форму можно одним щелчком соответствующей кнопки в Class Tool; можно генерировать либо плоский текст, либо текст в форматах HTML, RTF, MML (FrameMaker), TEX и других. Можно определить и свой собственный формат. |
Если сравнить краткую форму утверждений с их оригиналами в классе, то можно заметить, что исчезли все предложения, включающие
Краткая форма документации особенно интересна по следующим причинам:
[x]. Документация является более высокой формой абстракции, чем объект, который она описывает. Это основное требование, предъявляемое к качественной документации. Фактическая реализация, описывающая 'как', удаляется. Утверждения, объясняющие 'что', а в некоторых случаях и 'почему', остаются. Сохраняются заголовочные комментарии к программам и описания, включаемые в предложение
[x]. Являясь прямым следствием принципа Самодокументирования, изучаемого в нашем обзоре концепций модульности, краткая форма рассматривает документацию как информацию, содержащуюся в самом программном продукте. Это означает, что есть только один сопровождаемый продукт, - важное требование, проходящее через всю книгу. Как результат, появляется больше шансов корректности документации. Сохраняя все в одном месте, вы уменьшаете риск несоответствия документации обновленному продукту.
[x]. Краткая форма может быть извлечена из класса автоматически. Так что документация не есть нечто, требующее специального написания. Вместо этого, когда она необходима, вы просто 'просите компьютер' произвести это нечто, щелкнув кнопкой мыши.
Интересно сравнить этот подход с понятием интерфейса пакета в языке Ada, где модуль (пакет) состоит из двух частей - интерфейса и реализации. Java использует подобный механизм. Интерфейс пакета
