接口依赖的文档化和体系结构建模

Question

我有一个拥有数百万SLOC、数百个模块和数千个接口依赖项的大型软件系统。基于StackOverflow中早先的一个问题，我已经能够开始发现这些接口依赖项到底是什么。

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

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

有没有人有关于如何管理这么多专业数据的想法或例子？我曾考虑过尝试破解doxygen (我喜欢javadoc风格的输出)，但这似乎有很多工作要做。

Answer 1

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

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

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

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

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

Answer 2

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

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

我会从以下几个方面着手：

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

2)编写一个简单的程序，该程序将从excel生成一组HTML文件。这将帮助您更轻松地浏览和导航信息，作为进一步研究的起点。我不会在一开始就进入一个完全成熟的javadoc格式。从小规模开始，随着需求的出现，分阶段地发展你的程序\脚本。在这个过程中，您还会发现重构在哪里是有意义的。

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

我会创建一些本地的UML图，但不会超出控制范围--可能每个模块都有几个UML。以不同的方式标记对外部模块的依赖关系。(同样，自动化UML的生成将不会那么有用，它是在每个图中手工挑选有意义的接口，这将使文档中的UML最具启发性。)

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

Answer 3

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

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