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

Question

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

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

Я попробовал стандартные решения, такие как UML, но в итоге получается так много линий зависимости, что диаграммы выглядят как плотные паутины и бесполезны. Сейчас у меня есть таблица Excel, состоящая из 40000 строк, но это не очень удобно.

У кого-нибудь есть идеи или примеры того, как управлять этими очень специализированными данными? Я думал о попытке взломать doxygen (мне нравится вывод в стиле javadoc), но это похоже на большую работу.

Answer 1

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

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

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

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

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

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

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

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

Answer 2

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

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

Answer 3

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

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

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

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

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