Question

尽管软件指南的其他部分描述了软件的整体架构，但你还是想呈现底层细节，解释工作原理。这就是代码部分的目的。有些软件架构文档模板将其称为“实现视图”或“开发视图”。

意图

代码部分的目的是描述软件系统中重要、复杂、意义重大部分的实现细节。比如，我为自己曾参与过的软件项目写了以下内容。

生成/渲染HTML：对生成HTML的内部框架的简短描述，包括主要的类和概念。

数据绑定：根据HTTP POST请求更新业务对象的方法。

多页数据采集：简短描述构建跨网页表单的内部框架。

Web MVC：正在使用的Web MVC框架的一个使用示例。

安全性：使用Windows身份基础（WIF）进行认证和授权的方法。

域模型：域模型重要部分的概览。

组件框架：简短描述为了在运行时重新配置组件而构建的框架。

配置：简短描述代码库中使用的标准组件配置机制。

架构分层：分层策略和用来实现的模式的概览。

异常和日志：总结在各个架构分层中处理异常和记录日志的方法。

模式和原则：解释模式和原则如何实现。

等等。

结构

保持简单，每个想要描述的元素都只给一小段，如果对读者有帮助的话，还可以包含图表。举个例子，一个高层次的UML类或序列图有助于解释内部定制框架如何工作。抵挡住包含所有细节的诱惑，不要觉得你的图表需要展示一切。我喜欢花上几分钟时间勾画一个展示了选定（重要）属性和方法的高层次的UML类图，而不是使用UML工具或IDE插件从你的代码库自动生成的复杂图。任何图都保持在一个较高层次的细节意味着着它们能在更长时间内较少变动，保持最新，因为它们能够忍受代码的微小变化而仍然有效。

动机

写这个部分的动机是为了确保每个人都了解软件系统重要/意义重大/复杂的部分如何工作，这样人们就能够以一致和连贯的方式维护、增强和扩展它们。这个部分也有助于团队的新成员迅速行动起来。

受众

主要是软件开发团队中的技术人员。

是否必须

不是，但除了不重要的软件系统，我通常都会包含这个部分。