接口依赖的文档化和架构建模答案

【问题标题】：Documenting and Architectural Modeling of Interface Dependencies接口依赖的文档化和架构建模
【发布时间】：2009-10-20 21:00:07
【问题描述】：

我有一个包含数百万个 SLOC、数百个模块和数千个接口依赖项的大型软件系统。根据StackOverflow 中的一个较早问题，我已经能够开始发现这些接口依赖项实际上是什么。

现在的挑战是以有用的格式提供所有这些信息。数据在 SQL 数据库中，因此构建报告很容易，但我需要一种方法来实际对数据进行建模，以便用户轻松找到他们正在寻找的内容。

我尝试了像 UML 这样的标准解决方案，但最终依赖线太多，以至于图表看起来像密集的蜘蛛网并且毫无用处。现在我只有一个 40,000 行的 Excel 电子表格，但这不是很实用。

有人对如何管理如此专业的数据有任何想法或示例吗？我曾想过尝试破解 doxygen（我喜欢 javadoc 风格的输出），但这似乎需要做很多工作。

【问题讨论】：

【解决方案1】：

如果它是一个分解良好的系统，那么子系统内应该有相互关联的接口集群，但子系统之间只有少数接口。

如果它不是一个分解良好的系统，那么它在任何表示中都不会看起来很漂亮，并且消除存在链接的表示会歪曲这种情况。

一种选择是修剪只有一个依赖的接口，这将是图的叶子。重复这样做会将系统侵蚀为具有最紧密链接节点的骨架。

您可能还想执行拓扑排序，这将显示任何循环，并告诉您层的位置。

我不赞成 JavaDoc 对 40,000 个接口的概述 - JavaDoc 非常适合在分层排列的库中查找内容，但它根本不能很好地显示事物之间的联系。

【讨论】：

【解决方案2】：

我认为在您解决“我用什么技术创建文档”这个技术问题之前，有一些事情要做。

对系统的真正了解和理解超出了实际的接口关系和模块结构。它是对整个系统的理解，以及其中的各个部分对整体的贡献。

我会朝着以下方向前进：

1) 首先，尝试自上而下地理解系统。这意味着首先要了解模块的结构，并从自上而下地创建它们的一些表示。在此过程中，您可能会在当前 Excel 中不存在的模块上找到其他元数据。花点时间添加它，当你以后创建自动文档时它会最有用，因为它会反映系统结构上的“非显而易见”的知识。

2) 编写一个简单的程序，从 excel 中生成一组 HTML 文件。这将帮助您更轻松地浏览和导航信息，作为进一步调查的起点。一开始我不会使用完全成熟的 javadoc 格式。从小处着手，根据需要分阶段发展您的程序\脚本。在此过程中，您还将发现重构的意义所在。

3) 使用您的 HTML 输出来研究几个模块的结构，并了解接口的内部模式。是否有命名约定？重复模式？任何你可以推断出来但在 Excel 中没有明显记录的东西。

我会创建一些本地 UML 图，但大小不会失控 - 每个模块可能有几个 UML。以不同的方式标记对外部模块的依赖关系。（同样，自动 UML 的生成不会那么有用，它是在每个图表中手工挑选有意义的接口，这将使得文档中最有启发性的 UML。）

我认为一组 HTML 和 UML 的最终结果会是一个很好的最终结果。

【讨论】：

【解决方案3】：

现在 VSTS 2010 beta 1 已经发布，现在可能是观看视频 "Bottom-up" Design with Visual Studio Team System 2010 Architect 的好时机。

您甚至可能想在 Beta 版中尝试其中的一些功能。它作为 VM 发布，因此不会对您的系统造成危险。此外，您可以在不提交平台的情况下使用架构工具，因为您只是试图可视化您的代码，而不是开发更多代码。

【讨论】：