Документирование и архитектурное моделирование зависимостей интерфейса

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

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

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

Вы также можете выполнить топологическую сортировку, которая покажет любые циклы и скажет вам, где находятся слои.

Я не одобряю JavaDoc для обзора 40 000 интерфейсов — JavaDoc хорош для поиска вещей в иерархически организованной библиотеке, но он совсем не показывает связи между вещами.

Я думаю, что есть кое-что, что нужно сделать, прежде чем заняться техническим вопросом «на какой технологии я создаю документацию».

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

Я бы пошел по следующим направлениям:

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

2) Напишите простую программу, которая будет генерировать набор HTML-файлов из Excel. Это поможет вам легче просматривать информацию и ориентироваться в ней в качестве отправной точки для дальнейшего изучения. Вначале я бы не стал вдаваться в полноценный формат javadoc. Начните с малого и развивайте свою программу\скрипт поэтапно, по мере необходимости. В ходе этого процесса вы также обнаружите, где рефакторинг имеет смысл.

3) Используйте выходные данные HTML для исследования структуры нескольких модулей и достижения понимания внутренних шаблонов интерфейсов. Существуют ли соглашения об именах? Повторяющиеся узоры? Все, что вы можете вывести и явно не задокументировано уже в Excel.

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

Я думаю, что окончательный результат набора HTML и UML будет хорошим конечным результатом.

Теперь, когда вышла первая бета-версия VSTS 2010, самое время посмотреть видео Проектирование "снизу вверх" с помощью Visual Studio Team System 2010 Architect.

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