为什么要写ADR

架构决策记录，也称为ADR，是记录如何以及为什么在代码库中做出决策的好方法。我们已经开始在GitHub的移动团队中采用它们，记录影响iOS代码库和Android代码库的决策，以及影响这两个移动客户端的决策。

ADR在开放源码代码库中并不是最常见的，但自2017年以来，在像更多企业环境中那样的长期“进化”代码库中，ADR获得了更多的欢迎。

那么为什么要写ADR呢？既然已经做出了决定，为什么还要花时间记录一些事情呢？

ADR不是一个自我发现的过程，不是对你的决定进行反思的过程。ADR将帮助您在6-12个月后回忆起您在决定采用该架构时的心态。

ADR在做出决策时捕捉决策。ADR是您在会议上、在Zoom上、在Slake上或在Xcode中忙于各种概念验证所花费的所有分钟和小时的结果。您脑海中的所有上下文都有机会进入语言，这样当您沿着这条路重温体系结构时，您可以将该上下文重新输入到您的大脑中。

几个月后，当有人指责你，并问你GitHubAPIClient测试模块是如何工作的，真正的红利就来了。与设置30分钟的配对电话引导他们完成代码相比，现在您可以链接到您编写的ADR，以解释在构建GitHubAPIClient模块时做出的一些决定的更多信息。

ADR迫使您编写不止一句一行话“这是#3128的特性”。它们是一种更长的散文形式，以帮助您的团队成员理解为什么功能是以这种方式构建的，而不是以其他方式构建的(参见：ADR本身中的“考虑的替代方案”和“利弊”)。

对你来说简单的事情对你的队友来说可能很复杂。当你做决定时，花点时间写下你的思维过程，这会让你的队友有机会进入你的大脑。编写ADR允许“决策社会化”，在这种情况下，您的团队可以做出由团队负责维护的决策，而不是孤立地做出决策。

通过扩展您在Pull请求标题和描述中所写的内容(并且您仍在编写高质量的Pull请求描述，对吗？)，您可以为您的团队成员提供更多有关补丁或差异如何在更大的系统中工作的信息。

更好的是，通过在发布Pull请求之前编写ADR报告，您将从审查它的团队中获得更好的Pull请求审查。您不再需要解释APIClient+Caching.swft中的第387行将如何影响数据获取和缓存架构，因为您的队友已经从您写的关于“为电子标签实体添加缓存支持”的ADR中了解了您正在如何改变系统。

ADR不是为了让您炫耀自己有多聪明，也不是为了让人们奉承您构建的架构。ADR用于帮助新队友了解代码库以及它是如何随着时间的推移而演变的。

随着团队的扩大和壮大，队友之间的沟通线路也会增加。一个由三个人组成的团队只有三条沟通线路(A<；>；B、A<；>；C、B<；>；C)。四人团队有六人(A<；>；B、A<；>；C、A<；>；D、B<；>；C、B<；>；D、C<；>；D)。想为一个五六人的团队算算吗？14名工程师、2名设计师、2名PM和3名EM怎么样？

写下所做的决定有助于与你当前的队友沟通，也有助于与那些在团队扩大和发展过程中加入你团队的人沟通。通过以异步方式通知您的团队如何以及为什么做出决策，您不再需要在每个架构决策的基础上“跳上Zoom call”来加入每个新的队友。

在最好的情况下，你会让你的队友为你写新的ADR，而不是取代你过去做出的决定，这样你将来就可以向你的队友学习。

我希望这能说服您在我们构建数百万人使用的软件时记录您所做的决定！随着我们的团队变得越来越庞大，我们的代码库变得越来越纠结和纠结，架构决策记录是帮助未来的我们、我们当前的队友和未来的队友的一种很好的方式。