我加入了一个已经运行了几年的中型项目的中间阶段。问题之一是从未描述过描述体系结构的文档。现在，我被分配了编写架构描述的任务。

在从事该项目的过程中，我收集了编写文档所需的所有信息。由于还添加了一些功能，因此确定了一些代码，这些代码显然破坏了所描述的体系结构。

例如，GUI应该是没有业务逻辑的薄层。那就是我被告知的。该实现包含很多逻辑。

老板给我分配了任务，写了描述系统体系结构的文档。目标受众是从事该项目的现在和将来的开发人员。我需要描述应该是什么，但是我还需要以某种方式描述偏差。

那么，我应该在哪里描述这些问题呢？错误跟踪软件？还是应该在描述系统体系结构的文档中描述实现与体系结构的偏差？

如果要记录已经构建的系统的设计或体系结构，则该文档应将其描述为“已构建”，而不是“设计”或“预期”。如果体系结构中有奇异之处，则本文档应指出那些问题，并尽可能向读者解释。

如果您能够从一开始就从从事该系统工作的人员那里获得信息（或者至少要比您拥有更长的时间），那么获取有关实际意图以及架构和设计为何偏离此目的的更多信息将很有用。意向。

归根结底，设计文档应作为代码指南。如果该文档没有帮助新开发人员了解代码库的当前状态以及其结构，那么该文档将无用。

该文档应该是一个有效的文档，用于在开发过程中指导系统更改的未来规划和设计，然后相应地进行更新。随着设计随着时间的变化和发展，该文档还应该帮助开发人员了解为什么事情是现在的样子。

如果您正在寻找有关捕获体系结构的建议，我喜欢IEEE标准1016-2009 IEEE信息技术标准-系统设计-软件设计说明中提倡的方法。它为设计说明提供了合理的结构，可用于捕获体系结构和详细信息级别的设计信息。

我也认为这些偏差是技术债务的一种形式。解决问题可能是一项大任务，甚至是一个小项目，我建议使技术债务的存在更加明显。如果这意味着您使用缺陷跟踪工具，则可以在其中放置一个或多个问题。如果您使用其他工具来跟踪软件的建议和增强功能，则可能是放置该工具的另一个地方。

在对系统的体系结构进行形式化时，重要的是，不仅要了解体系结构将带来的价值，而且要理解和理解它应该是什么。

软件或技术体系结构的主要目标是确定将驱动系统体系结构的质量属性实现的非功能性需求。

关于非功能需求：

非功能需求是指指定可用于判断系统运行的标准的需求，而不是特定行为。它们与定义特定行为或功能的功能需求形成对比。系统设计中详细说明了实现功能需求的计划。系统体系结构中详细介绍了用于实现非功能性需求的计划。

广义上，功能需求定义了系统应该做什么，而非功能需求定义了系统应该如何运作。非功能性需求通常被称为系统的“质量属性”。非功能需求的其他术语是“质量”，“质量目标”，“服务质量需求”，“约束”和“非行为需求”

当然，在新建项目中确定对体系结构具有重要意义的需求是有意义的，但是，在使用现有软件时，最好尽可能地加以约束。您不会希望您的软件体系结构受到现有系统的影响。

权威的软件架构实际上需要三件事。

陈述式

这是文档的一部分，在其中声明“不是什么”，但声明应该如何。我们通过使用系统的各种体系结构视图来做到这一点。我们定义了应该使用的组件，它们如何交互，然后有选择地深入每个组件以获得更详细的视图，这些视图声明了系统的设计方式。

这是一个重要的区别。系统设计应受系统体系结构的约束，它们实际上是独立的但相关的事物。

基本原理

您的软件体系结构的基本原理是为所做出的体系结构决策提供合法性和权威性。也许决定通过MQ上的Pub / Sub事件侦听器来触发批处理作业，然后您将其绘制出来？

为什么做出这个决定？我们在“原理”部分中解释原因，并将我们的解释链接回非功能性需求，质量属性目标或体系结构上重要的需求。（例如，作业必须是异步且可重复的，作为质量属性的可维护性促使在批处理作业失败的情况下可以通过MQ消息重新启动作业，系统必须通过异步通信将消息丢失为零，等等。 ..）

风险性

既然您已经声明了架构的方式并通过基本原理对其进行了证明，那么您现在可以确定系统当前状态中不遵守的风险。

（例如，服务器端验证是在客户端Javascript代码上重复的。这违反了DRY原则，这与可维护性的质量属性背道而驰。在该领域，围绕性能没有定义非功能性要求，因此是当前系统行为的基本原理）

您的风险还可以显示当前状态当前偏离体系结构的位置。开发团队现在可以通过他们的项目计划或将其添加到待办事项中来解决这些风险。

您确实确实需要确定是要记录项目的当前结构，还是要记录项目的期望结构，或两者都记录在案。

您可以记录该目标，以按照预期的方式指导将来的开发，并以错误的形式提出偏差（也许从文档的相关部分链接到这些错误）。或者，您可以记录实际情况，以便对代码进行介绍/概述。或者，您可以同时编写两个文档，以便同时在一个地方获得有关将来开发的指南和对当前代码的准确描述。一切都是合理的，取决于文档的用途，所以我认为我们无法有效地告诉您要执行哪个操作。

您还应该记住，所涉及的架构可能不会在参与的各方之间达成一致（要么是因为他们想要不同的东西，要么是因为其中一些人意识到某些原始的共同愿望是不可能或不切实际的，因此诉诸于编写现有代码）偏离目标）。因此，您还需要知道您是否有权决定所需的内容，如果没有，则由谁来决定。现有的结构至少具有这样的优点：只有一个要记录！

在体系结构设计文档中写出预期的内容，对于每个冲突，您都会在错误跟踪器中打开一张票证来描述冲突。票证的评论部分将为相关人员提供一个讨论特定冲突的平台。

请注意，每张票证的分辨率可以是更改实现以匹配设计-但也可以更改设计以匹配实现。理想情况下，前者是首选，但有时存在技术和/或业务限制，因此选择后者更为有效/务实/可行。在这种情况下，最好参考体系结构设计文档中的故障单，以便将来不了解为何选择特定劣质设计选择的读者可以阅读故障单中的讨论并理解其背后的原因。它。

我倾向于写一个分为3个主要部分的建筑文档。

首先介绍最初打算的设计/架构。这将使新的开发人员/读者可以了解系统应该做什么，并且显然应该与需求/用例等联系在一起。

第二部分应该非常清楚地确切解释该体系结构实际上是什么。这使新的开发人员/阅读者可以了解当前的游戏状态以及如果他们查看软件（以及其他文档）时要处理的内容。本部分应明确说明意图与现实之间的区别，因为这很可能会突出显示某些问题，这些问题可能与原始体系结构非常不正确（希望不是太多！）以及快捷方式/被黑客攻击的区域（如果有的话可能很少）已经给开发团队带来了很大的压力），并且没有满足要求，或者该软件开始看起来“设计得很差”，即脆弱，不稳定，不可移植。

最后，我想一个小节，详细介绍有关现在需要做什么的建议。这应该是对体系结构/设计的任何更改，以及当前对软件进行更改的路线图，以使您的愿景变为现实。

我认为这涵盖了（从高层次上）需要捕获的内容。根据您使用的文档或错误跟踪软件的子部分，如何执行此操作取决于您正在工作的领域/个人喜好/团队规模/预算/时间范围等。