1.7　固有文档

你可能已经看过Google数据中心和巴黎蓬皮杜艺术中心的照片（见图1-9）。它们都有许多用颜色编码的管道，并在管道上印刷或铆接了其他标签。在蓬皮杜艺术中心，空气管是蓝色的，水管是绿色的。这种用颜色编码的逻辑不仅用于管道，还用于其他地方，比如电力传输线是黄色的，而与人移动相关的一切（包括电梯和楼梯）都是红色的。

这种逻辑在数据中心也被广泛使用，甚至越来越多的文档直接印在了管道上。管道上有标签用于标识，而且会有箭头指示管道中的水流方向。在真实世界中，防火和消防通常必须使用这种颜色编码和特殊标记——消防员所用的水管上铆接了可见标签，指示它们来自何处。建筑物的紧急出口上方会有非常明显的指示。在飞机上，中间走道上的明亮标志指示去向。在危急情况下，你没有时间去找手册，答案需要位于最明显的地方：你当前所在的位置，也就是事物本身上。

1.7.1　固有文档与外部文档

持久性文档有两种形式：外部文档和固有文档。

如果知识被编写成外部文档，那么文档的形式与你所选择的项目实现技术将完全无关。传统形式的文档就是这种情况，即共享文件夹里存着的独立Microsoft Office文档或带有数据库的Wiki站点。

外部文档的优点在于，它会采用对读者和文档工程师来说最方便的格式和工具。它们的缺点是，要确保与产品版本保持同步更新非常困难（尽管也有可能做到），而且很容易丢失。

相反，固有文档通过使用现有的实现技术直接表达知识。固有文档的一个良好示例是：在语言标识符上使用Java注解或命名约定来声明和解释设计决策。

固有文档的优点在于，它是源代码的一部分，所以始终与产品版本保持同步更新。因为固有文档内嵌在源代码中，所以它们不会丢失。因为固有文档就在开发人员的眼皮子底下，所以它们随时可用，而且所有正在开发相关代码的开发人员都会注意到它们。

固有文档还能使你从出色的IDE的所有工具和优点中受益，例如自动补全、即时搜索以及元素内部和元素之间的无缝导航。固有文档的缺点是你的知识表达受限于语言内置的扩展机制。例如，你几乎不可能用每个依赖项的额外知识扩展Maven XML。另一个很大的缺点是，非开发人员不容易获得固有文档记录的知识。但是，我们也可以通过自动化机制来解决这个限制。这种自动化机制可以提取知识并将其转换为目标受众可以访问的文档。

如果你熟悉Martin Fowler和Rebecca Parsons的《领域特定语言》一书，就会知道内部领域特定语言和外部领域特定语言的相似概念。外部领域特定语言独立于所选的实现技术。例如，正则表达式的语法与项目所选择的编程语言无关。相反，内部领域特定语言使用通常会选择的技术（例如Java编程语言），从而使它看起来像另一种语言。这种风格通常被称为 流畅 风格，而且在模拟库中很常见。

1.7.2　固有文档与外部文档示例

判断一个文档是固有的还是外部的并不那么容易，因为有时这与你看它的角度有关。Javadoc是Java编程语言的标准组成部分，因此是固有文档。但是从Java实现者的角度来看，它是Java语法中嵌入的另一种语法，因此是外部文档。位于灰色中间区域的常规代码注释是语言的正式组成部分，但它们只是一些自定义文本，不提供其他任何功能。你可以自由发挥、自行撰写，而且编译器只会根据英语词典做默认的拼写检查，不会帮助检查其他输入错误。

从开发人员的角度来看，用于构建软件产品的每种标准技术都包含固有文档。

• 用于业务可读的需求说明和测试工具的功能文件。
• 紧随代码出现的Markdown文件和图片：带有命名约定，或者从代码或功能文件链接过去。
• 工具清单，包括依赖关系管理清单、自动部署清单、基础结构描述清单等。

每当我们在这些工件中添加文档时，都会因为能使用标准工具集而受益，而且，因为文档就在源代码控制系统中并且靠近相应的实现代码，所以能与代码一起发展变化。

可用于制作固有文档的方法举例如下。

• 自记录代码和使用简洁代码的实践，包括类和方法的命名，使用组合的方法和类型。
• 将知识添加到编程语言元素中的注解。
• 对公共接口、类和主要方法的Javadoc注释。
• 文件夹组织方式，以及模块和子模块的分解和命名。

外部文档包括如下示例。

• README和类似的文本文件。
• 项目相关的任何HTML文档或Microsoft Office文档。

1.7.3　首选固有文档

就像你在本书中所看到的那样，我绝对支持固有文档。它还应提供足够的自动化功能，用于一些需要发布更多传统文档的情况。我建议你默认选择固有文档，这样至少可以处理那些经常变更的知识。

即使是对于稳定的知识，我也建议你优先使用固有文档。除非编写成外部文档能明显地为知识增值，否则我不会使用外部文档。例如，一个文档必须极有吸引力（可能出于营销原因），在这种情况下，我建议你使用手工制作的幻灯片、精心设计的图表和精美的图片。使用外部文档的意义在于能在最终文档中增添些许人情味，因此我会使用Apple Keynote或Microsoft PowerPoint，选择或创建精美的图片，并召集同事一起对文档的效果做β测试，确保它能受到好评。

请注意，吸引力和幽默很难自动化或编码到正式文档中，但也不是不可能。

1.7.4　就地文档

固有文档也是一种就地文档，即“在原地”的文档。

这意味着在构建产品的工件中，文档不仅使用相同的实现技术，而且也直接混在了源代码中。“在原地”意味着将有关事物的附加知识放到事物所处的位置，例如放到源代码中，而不是远离源代码的位置。

这种文档对开发人员来说很方便。在设计用户界面时，术语“在原地”意味着用户不需要转到另一个窗口就可以执行特定的用户操作，而回到文档上来，“在原地”是指开发人员不需要打开另一个文件或使用另一个工具就能使用和编辑文档。

1.7.5　机器可读的文档

好的文档重点关注高级知识，例如代码顶部描述的设计决策以及这些决策背后的依据。我们一般认为只有人类才对这种知识感兴趣，实际上，工具也能利用它们。由于固有文档是使用实现技术表示的，因此通常只能用工具解析它们。这为工具提供了新机会来帮助开发人员完成日常任务。尤其是，这个过程能自动处理知识以进行管理、合并、格式转换、自动发布或保持一致。 MdGsjbohf+1Ul6iWf6LdjufhmS4Qeek5T3YEuwpDOQPWPNKu20TVzexAhmgbDXI5