万能的砰的一声

作者：Martin Fowler：分布式计算 1997 年 11 月/12 月刊专栏

我正在和一位客户聊天，他们想让我对他们的对象模型进行审查。“我们可以提前发送一些文档，这对您有用吗？”他们问道。我肯定地回答，希望自己没有说谎。两天后，UPS 送货员把包裹放在我家门口，发出很大的响声。它足足有一英寸半厚。

我打开它，发现里面是 CASE 工具打印出来的内容。它显示了一些图表，并对每个类、每个属性和每个操作进行了详尽的描述。所有这些都有定义。Contract 类被定义为“多方之间的合同”，其 dateSigned 属性被定义为“合同签署的日期”。我浏览了这英寸半厚的文档，但最终我并没有变得更明智。关于对象是什么有很多内容，但几乎没有解释它们应该做什么。这不是第一次发生，如果这是最后一次，我会感到惊讶。

我们为什么要费心去创建模型或文档？它们不会执行，我们的客户为我们付钱是为了得到可运行的代码，而不是漂亮的图片。我们费心去创建模型是为了沟通。想法是，图形对象模型可以比查看源代码更清楚地显示对象如何组合在一起，交互图可以比从多个类定义中找出调用路径更好地显示协作。但是，设计文档经常在这方面失败，让我坐在沙发上感到困惑。

问题的一部分是人们用于此类工作的 CASE 工具。（CASE 工具有两个目的，文档和代码生成，这里我只谈论前者。）CASE 工具鼓励字典思维方式。您为每个类创建一个条目，您在图表上显示每个类和每个属性，您为每个用例绘制一个交互图。它们通过帮助您回答“我们是否记录了所有内容？”来鼓励完整性。

但这个问题问错了。如果您记录所有内容，您就是在赋予所有内容同等权重。对于一个复杂的系统，这样做会让您淹没在细节中。在任何系统中，有些方面比其他方面更重要，系统的关键方面一旦理解，将有助于某人学习更多。文档的艺术在于找到如何尽可能清晰地记录这些方面。这样，您就会强调这些领域，并将细节留给代码。

最重要的是，文档必须简短。只有简短，人们才会阅读和理解它。只有简短，您才会费心去更新它。您无法谈论所有内容，也不应该谈论所有内容。我的一位朋友告诉我，在一个项目中，他们不愿意更改类名，不是因为代码更改需要太长时间，而是因为文档更改需要太长时间。当文档成为问题时，您应该处理它。至少扔掉一半。

您应该说什么？

如果您的系统规模合理，请将您的系统划分为包（如 UML 或 Java）。每个包都包含一组为特定目的协同工作的类。使用显示包及其依赖关系的图表来记录系统的整体结构。（在 UML 中，这是类图的特定用法，我经常使用它，所以我喜欢将其命名为包图，请参阅我的书《UML精粹》。）使用您的设计来最小化这些依赖关系，这是最小化系统耦合的关键。（关于如何做到这一点，没有太多可读的资料，我知道的最好的资料是 Robert Martin 的《使用 Booch 方法设计面向对象 C++ 应用程序》。）

对于每个包，编写一份简短的文档。文档的基础是一些描述包执行的关键内容以及如何执行的叙述性文本。UML 图表可用于帮助支持这一点。绘制一个类图，显示包中重要的类，但不一定显示所有类。对于每个类，只显示关键属性和操作，绝对不要显示所有属性和操作。专注于接口而不是实现。对于包中的每个重要协作，显示一个交互图。如果任何类具有有趣的生命周期行为，则使用状态图显示它。文档应该足够小，以至于您不会发现更新它是一个问题。我通常会尝试将其限制在不超过十页。

除了每个包的文档之外，显示协作如何跨越包也是有用的。为此，请识别系统中的关键用例，并使用交互图和叙述性文本记录它们。突出显示相关关键类的类图也很有用。许多人主张为系统中的每个用例绘制交互图。我觉得这会导致过多的文档，但如果您发现它有用，并且发现更新它不是问题，那么请继续进行。即使这样，您也应该识别不超过十几个关键用例，并将它们突出显示为每个人都需要理解的用例。

沟通是关键

在整篇文章中，我都在强调沟通。我批评了 CASE 工具，但这主要是为了说明使用工具本身并不意味着您在进行沟通。任何工具都可以帮助或阻碍沟通，您如何使用它决定了结果。

我知道的一个项目购买了一个多用户 CASE 工具，任何开发人员都可以从他们的工作站访问该工具。所有设计都必须放入 CASE 工具中。但仅仅因为任何开发人员都可以使用它，并不意味着每个开发人员都会使用它。实际上，很少有开发人员查看 CASE 工具中的模型，更少的人理解它们。意识到这一点后，该项目的架构师接管了办公室的一块墙壁，并在上面贴了一系列图表，显示了系统中六个关键协作。他使用带颜色编码的对象图显示它们，以帮助强调正在发生的事情。这并不意味着所有开发人员都理解所有设计，但至少现在他们可以看到重要的元素是什么。

当我开始写这篇文章时，我被我能谈论的事情所淹没。许多轶事和技巧浮现在脑海。但我知道，为了让您阅读并记住这篇文章，我只能谈论其中的一部分。我必须选择我必须提到的关键内容。沟通就是关于这一点。良好沟通的关键是突出显示要说的重要内容。说所有内容不是沟通。这只会将重要内容的选择传递给您的读者，并用沉重的文档来阻止他们。信息的选择是沟通中最重要的部分之一，这是每个设计师的责任。