Question

敏捷软件开发宣言1说“ 可以工作的软件重于面面俱到的文档”，看到很多软件团队将其解释成“不写任何文档”真是令人难以置信。其中的基本原理是，对最终用户来说真正工作的软件比一堆面面俱到的文档有价值得多，但是很多团队把敏捷宣言中的这句话当成了完全不写任何文档的借口。很遗憾，代码不会讲述完整的故事，缺少关于复杂软件系统的辅助信息源会让团队在努力浏览代码时被拖累。

1http://agilemanifesto.org

我也坚信，软件团队有义务和代码库一起交付一些辅助文档，特别是那些在外包或离岸合同下构建软件的团队。我见过IT咨询组织交付高度复杂的软件系统给客户时甚至没有一页支持文档，往往是因为团队就没有任何文档。如果原来的软件开发者离开了咨询组织，新的团队能否理解软件的方方面面，它如何构建以及如何以契合原始架构的方式增强？那可怜的客户怎么办？是不是应该只交付给他们可工作的代码库？

问题是，当软件团队考虑文档时，他们通常想到的是基于一个1990年代软件架构文档模板的庞大微软Word文档，其中还包括一个需要为他们的软件支持的每一个用例绘制统一建模语言（UML）类图的部分。几乎没有人喜欢阅读这种类型的文档，更别说写了！我们需要一种不同的方法。我们应该考虑把辅助文档作为一个不断变化的旅游指南，而不是一个综合的静态历史片断。但这样的指南应该写些什么？

1. 地图

让我们想象一下，我把你传送出去，丢到世界上某处一条安静、树木茂密的乡间小道（图1）。你在哪里，如何找到这个问题的答案？你可以大声呼救，但这只在附近有人的时候才管用。或者你可以抬腿就走，直到认出什么东西，或者遇到某些文明后向他们寻求帮助。作为极客，我们可能会打开智能手机上的地图应用程序，用GPS来确定方位（图2）。

从细节到大局

图2的问题是，尽管它可以显示我们的方位，但“放大”得有点多，没有什么意义。如果进一步缩小，最终我们会看到，我把你传送到了泽西的一条乡间小道（图3）。

接下来的问题，卫星图像显示了很多细节，相对于岛上一些显著的特征，如主要的道路和场所，很难看出我们在哪里。为了解决这个问题，我们可以移除卫星图像（图4）。尽管没有那么详细，这种抽象却让我们看到了岛上一些主要的结构元素以及地名，这正是之前被细节掩盖的。有了这张岛的简化视图，我们可以进一步缩小，直到得到一张显示了泽西在欧洲的确切位置的大图（图5、图6和图7）。所有这些图像从不同的抽象层次显示了同一个方位，每一个都可以帮助你回答不同的问题。

如果我打开一个复杂软件系统的代码库，随机突出一行代码，探索会很有趣，但要搞明白你在哪里以及代码如何融入软件系统这个整体，都要花一些时间。大多数集成开发环境都有办法通过命名空间、包或文件夹来浏览代码，但代码库的物理结构和逻辑结构往往是不同的。举个例子，你可以用很多个类组成一个组件，用那些组件再组成一个可部署单元。

图表可以作为地图来帮助人们浏览一个复杂的代码库，这是软件的辅助文档最重要的组成之一。理想情况下，应该有数张简单的图表，各自展示软件系统或抽象层次的不同部分。我的C4方法就总结了软件系统的静态结构，但也有包括应用UML在内的其他方法。

2. 景色

如果去泽西2，你很可能想要一张地图。你真的应该去，那里太美了。港口有游客地图，简洁地展示了泽西的外貌。基本上，游客地图就是这个岛的详细草图，它们显示了抽象的外观，而不是展示每一栋建筑。虽然泽西岛很小，如果你没去过的话，这些地图打开一看也会很吓人，因此理想状态下你需要一个主要兴趣点和景点的清单。这是人们在假期会随身携带度假指南的的主要原因之一。无论是现实的还是虚拟的（例如你的智能手机上的一本电子书），指南无疑都会列出一份你不能不看的顶级景点的清单。

2http://www.jersey.com

代码库也没有什么不同。尽管我们可以花很长一段时间绘图和描述每一段代码，但这样做真的价值不大。我们真正需要的是列出兴趣点，这样就能集中精力去理解软件的主要元素而无需陷入所有的细节。举个例子，很多Web应用程序实际上都相当无聊，相比于理解200多页的每一页都如何工作，我宁愿看看兴趣点。这可能包括实现Web页面和数据访问策略，以及处理安全性和可伸缩性的专利。

3. 历史和文化

如果你去过泽西，你可能会看到一些看起来偏离了环境的东西，举个例子，在岛的南部海岸，我们有一个可爱的建于16世纪的花岗岩石城堡，叫做伊丽莎白城堡3。你一边走一边欣赏建筑，最终会到达顶部，在那里它看起来就像有人卸下的一根混凝土大柱子。这跟城堡周围随处可见的复杂的花岗岩石雕格格不入。当你进一步探索，还会看到有迹象表明城堡在二战德国占领期间加固过。看，历史有助于解释为什么城堡是这样的。

3http://www.jersey.com/English/sightsandactivities/attractions/attractions/Pages/elizabethcastle.aspx

再次，代码库没有什么不同，一些历史、文化和理念的知识能够长期地帮助你理解为什么一个软件系统是那样设计的。这对那些新加入一个现有团队的人特别有用。

4. 实用信息

旅游指南可能会包含的最后一件事就是实用信息。你知道，所有关于货币、电力供应、移民、地方法律、当地习俗、遇到困难如何解决等有用的小知识。

如果我们考虑一个软件系统，实用的信息可能包括在哪里找到源代码、如何构建、如何部署、团队遵循的原则，等等。所有这些都能帮助开发团队做好他们的工作。

保持短小简洁

探索十分有趣，但始终要花时间，而我们往往没有时间。既然代码不会讲述完整的故事，一些辅助文档就非常有用，特别是如果你把软件交接给其他人或者经常有人离开和加入的团队。我的建议是，把这个辅助文档当作一个指南，它应该给人们上手提供足够的信息，帮助他们加快探索的过程。不过要抵挡住深入太多技术细节的诱惑，因为理解那个层次细节的技术人员自然知道如何从代码库找到它。和任何事一样，其中有一个愉快的平衡点。

以下标题描述了你可能想要包含在软件指南中的事情：

1.语境；

2.功能性概览；

3.质量属性；

4.约束；

5.原则；

6.软件架构；

7.外部接口；

8.代码；

9.数据；

10.基础设施架构；

11.部署；

12.运营和支持；

13.决策日志。

注意“视图”

很多典型的软件架构文档模板用来编写辅助文档实际上没有那么糟，但各个部分的名字往往令人困惑。如果你看了我刚才展示的标题清单，可能会好奇，典型的软件架构“视图”在哪里。

如果你以前没见看过这些，就有很多不同的方式来察看一个软件系统。例子有IEEE 14714、ISO/IEC/IEEE 42010 5、菲利浦·克鲁西腾（Philippe Kruchten）6的4+1模型7等。它们的共同之处是都给一个软件系统提供了不同的“视图”来描述不同的方面。比如，通常有“逻辑视图”、“物理视图”、“开发视图”，等等。

4http://en.wikipedia.org/wiki/IEEE_1471

5http://en.wikipedia.org/wiki/ISO/IEC_42010

6加拿大软件工程师，英属哥伦比亚大学教授，http://en.wikipedia.org/wiki/Philippe_Kruchten。——译者注

7http://en.wikipedia.org/wiki/4%2B1_architectural_view_model

我发现很多方法都有个大问题，如果人们不熟悉方法使用的术语，很快就会变得困惑。比如，我听过到有人争论“概念视图”和“逻辑视图”有什么不同。我们还是不要开始关于是否允许技术出现在逻辑视图的问题吧！观点也很重要。如果我是一个软件开发者，“开发视图”是不是就是代码，或是说那叫“实施视图”？但“物理视图”又是什么？我的意思是，代码就是物理输出，对吧？但对基础设施架构师而言，“物理视图”又是另一个意思。但是，假如目标部署环境是虚拟的而非物理的呢？

我的建议是，不管你如何编写文档，只要明白你想传达的是什么，并相应地给各部分命名。解决术语问题的一个选项是确保团队中每个人对各种架构视图是什么都能找到清晰的定义。在这方面，我高度推荐约恩·伍兹（Eoin Woods）和尼克·罗桑斯基（Nick Rozanski）所著的《软件系统架构》8。另一个方法是就是将各个部分重新命名来消除歧义。

8http://www.viewpoints-and-perspectives.info

产品与项目文档

最后一点，我这里指的文档风格是跟所构建的产品有关，而不是创建/改变这个产品的项目。和我一起工作过的一些组织有将近二十年的软件系统，尽管它们有不同数量的项目级文档，其中却往往没有一个能讲述产品如何工作、如何演化。通常这些组织有只有一个产品（软件系统），每一次主要的变化都作为一个单独项目来管理，结果过去20年中产品发生了巨大的变化，为了解软件当前的状态，要消化相当数量的项目文档。在这样的环境中，新员工往往只能读读代码，跟踪不同项目组产出的文档来填补空白，这至少是浪费时间！

我建议软件团队为他们构建的每一款软件系统都创建一份软件指南。这并不意味着团队不应该创建项目级别的文档，但应该有一个地方可以让人找到关于产品如何工作、如何随着时间演化的信息。一旦有了这样的软件指南，改变一个系统的每一个项目/变化流/时间段就是一个小的增量。每款产品一份软件指南，使得了解软件当前的状态变得简单得多，也为将来的探索提供了非常好的起点。