Документирование интерфейсов

Интерфейс (interface) — это граница, на которой встречаются, взаимодействуют между собой или передают друг другу информацию две независимые сущности.

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

Под документированием интерфейса подразумевается указание его имени, идентификация, а также отражение всех синтаксических и семантических сведений о нем. Первые два элемента — указание имени и идентификация — обобщенно называются «сигнатурой» интерфейса. Если в качестве ресурсов интерфейса выступают вызываемые программы, сигнатура обозначает их и определяет их параметры. Параметры определяются по порядку, типу данных и (иногда) по принципу возможности изменения их значений программой. Та информация о программе, которая содержится в сигнатуре, обычно приводится в заголовочных файлах С или C++ и в интерфейсах Java.

При всей полезности сигнатур (в частности, они делают возможной автоматическую проверку конструкций) ими все не исчерпывается. Соответствие сигнатур обеспечивает успешную компиляцию и/или компоновку системы, но совершенно не гарантирует достижение конечной цели — ее нормальное функционирование. Необходимая для этого информация относится к семантике интерфейса, которая сообщает, что происходит при активизации ресурсов.

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

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