Google软件工程文明的一个要害要素是运用规划文档来界说软件规划。这些相对非正式的文件由软件体系或应用程序的首要作者在开端编码项目之前创立。规划文档记载了高层次的完结战略和要害规划决议方案，要点强调在这些决议方案过程中考虑到的权衡。

作为软件工程师，咱们的使命不仅仅是生成代码，而更多地是处理问题。像规划文档这样的非结构化文本或许是项目生命周期前期处理问题更好的东西，由于它或许更简练易懂，而且以比代码更高层次的办法传达问题和处理方案。

除了原始软件规划文件外，规划文档还在以下方面发挥着作用：

在进行变更时及早识别出规划问题依然较廉价。

在组织内达成对某个规划方案的一致。

保证考虑到跨领域关注点。

将资深工程师们掌握常识扩展到整个组织中去。

形成围绕规划决议方案建立起来的组织记忆基础。

作为技能人员出资组合中一份摘要性产物存在于其间。

规划文档的构成

规划文档对错正式的文件，因此其内容没有严厉的指导方针。第一条规矩是：以对特定项目最有意义的办法编写。

话虽如此，事实证明，某种结构现已被证明十分有用。

上下文和规模

本节为读者供给了新体系构建的大致概述以及实践正在构建的内容。这不是一份需求文档。保持简练！方针是让读者灵敏了解状况，但能够假设有一些先前的常识，而且能够链接到详细信息。本节应彻底专心于客观布景事实。

方针和非方针

列出体系方针的简略项目列表，有时更重要的是列出非方针。请注意，非方针并不是否定性的方针，比方“体系不应崩溃”，而是清晰挑选不作为方针而合理或许成为方针的事项。一个很好的比如便是“ACID兼容性”；在规划数据库时，您肯定想知道是否将其作为一个方针或非方针。假如它是一个非方针，则依然能够挑选供给该功用的处理方案，前提是它不会引进阻碍完结这些方针的权衡考虑。

实践规划

这一部分应该以概述开端，然后进入细节。

规划文档是记载你在软件规划中所做的权衡的当地。专心于这些权衡，以发生具有长时刻价值的有用文档。也便是说，在给定上下文（事实）、方针和非方针（需求）的状况下，规划文档是提出处理方案并展现为什么特定处理方案最能满意这些方针的当地。

编撰文件而不是运用更正式的媒介之一的原因在于供给灵活性，以恰当办法表达手头问题集。因此，并没有清晰指导怎么描绘规划。

话虽如此，现已呈现了一些最佳实践和重复主题，在大多数规划文档中都很合理：

体系上下文图

在许多文档中，体系上下文图十分有用。这样的图表将体系显示为更大的技能环境的一部分，并答应读者依据他们现已熟悉的环境来了解新规划。

APIs

假如规划的体系暴露出一个API，那么草拟出该API一般是个好主意。但是，在大多数状况下，应该抵抗将正式接口或数据界说复制粘贴到文档中的诱惑，由于这些界说一般冗长、包括不必要的细节，而且很快就会过时。相反，要点关注与规划及其权衡相关的部分。

数据存储

存储数据的体系或许需求谈论怎么以及以什么样的办法进行存储。与对API的主张相似，出于同样的原因，应避免彻底复制粘贴形式界说。而是专心于与规划及其权衡相关的部分。

代码和伪代码

规划文档很少包括代码或伪代码，除非描绘了新颖的算法。在恰当的状况下，能够链接到展现规划可完结性的原型。

束缚程度

影响软件规划和规划文档形状的首要因素之一是处理方案空间的束缚程度。

在极点状况下，有一个“全新软件项目”，咱们只知道方针，处理方案可所以任何最合理的挑选。这样的文档或许触及规模广泛，但也需求快速界说一组规矩，以便缩小到可办理的处理方案集。

另一种状况是体系中或许存在十分清晰界说的处理方案，但怎么将它们结合起来完结方针并不明显。这或许是一个难以更改且未规划为满意您期望功用需求的留传体系，或许是需求在主机编程言语束缚下运行的库规划。

在这种状况下，您或许能够相对容易地列举出一切能够做到的工作，但需求创造性地将这些事物组合起来完结方针。或许会有多个处理方案，而且没有一个真正很好，在识别了一切权衡后该文档应专心于挑选最佳办法。

考虑的代替方案

本节列出了其他或许到达相似结果的规划方案。要点应放在每个规划方案所做的权衡以及这些权衡怎么导致挑选文档主题中所述规划的决议方案上。

虽然关于最终未被选中的处理方案能够简练地进行描绘，可是这一部分十分重要，由于它清晰展现了依据项目方针而挑选该处理方案为最佳选项，而且还说明晰其他处理方案引进了不太理想的权衡，读者或许会对此发生疑问。

穿插关注点

这是您的组织能够保证始终考虑到安全、隐私和可调查性等特定的穿插关注点的当地。这些一般是相对简略的部分，解说规划怎么影响相关问题以及怎么处理这些问题。团队应该在他们自己的状况下标准化这些关注点。

由于其重要性，Google项目需求有专门的隐私规划文档，而且还有专门针对隐私和安全进行Review。虽然Review只要求在项目启动之前完结，但最佳实践是尽早与隐私和安全团队协作，以保证从一开端就将其归入规划中。假如针对这些主题有专门文档，则中心规划文档当然能够引用它们而不胪陈。

规划文档的长度

规划文档应该满足详细，但又要短到忙碌的人实践上能读完。关于较大的项目来说，最佳页数好像在10-20页左右。假如超越这个规模，或许需求将问题拆分成更易办理的子问题。还应注意到，彻底能够编写一个1-3页的“迷你规划文档”。这关于灵敏项目中的增量改善或子使命尤其有协助 – 你依然按照长篇文档相同进行一切过程，只是保持简练，并专心于有限的问题集合。

何时不需求编写规划文档

编写规划文档是一种额定的工作量。是否要编写规划文档的决议方案取决于中心权衡，即组织一致在规划、文档、高级Review等方面的优点是否超越了创立文档所需的额定工作量。这个决议方案的中心在于处理规划问题是否含糊——由于问题复杂性或处理方案复杂性，或许两者都有。假如不含糊，则经过编撰文档来进行流程或许没有太大价值。

一个清晰的指标表明或许不需求文档是那些实践上只是施行手册而非规划文档。假如一个文件根本上说“这便是咱们将怎么完结它”，而没有触及权衡、代替方案和解说决议方案（或许处理方案明显意味着没有任何权衡），那么直接编写程序或许会更好。

最后，创立和Review规划文档所需的开销或许与原型制造和快速迭代不兼容。但是，大多数软件项目的确存在一系列已知问题。遵从灵敏办法论并不能成为对真正已知问题找到正确处理方案时刻投入不足的托言。此外，原型制造本身可所以规划文档创立的一部分。“我尝试过，它有效”是挑选一个规划方案的最佳论据之一。

规划文档的生命周期

规划文档的生命周期包括以下过程：

创立和快速迭代 Review（或许需求多轮） 施行和迭代 保护和学习

创作和快速迭代

你编撰文档。有时与一组合著者共同完结。

这个阶段很快进入了一个快速迭代的时刻，文档会与那些对问题领域最了解的搭档（一般是同一个团队的人）共享，并经过他们提出的弄清问题和主张来推动文档到达第一个相对安稳版别。

虽然你肯定会找到一些工程师甚至团队更喜爱运用版别操控和代码Review东西来创立文档，但在谷歌，绝大多数规划文档都是在Google Docs中创立并广泛运用其协作功用。

Review

在Review阶段，规划文档会与比原始作者和严密协作者更广泛的受众共享。Review能够增加很多价值，但也是一个风险的开销陷阱，所以要正确地对待。

Review能够采纳多种办法：较轻量级的版别是将文档发送给（更广泛的）团队列表，让大家有机会看一下。然后首要经过文档中的谈论线程进行谈论。在Review方面较重型的办法是正式的规划评审会议，在这些会议上作者一般经过专门制造的演示文稿向经历丰富、资深工程师们展现该文档内容。谷歌公司许多团队都定期组织了此类会议，并邀请工程师参与审核。自但是然地等待这样的会议或许会显著减慢开发过程。工程师能够经过直接寻求最要害反应并不阻碍整体审核进度来缓解这个问题。

当谷歌仍是一家较小的公司时，一般会将规划发送到一个中心邮件列表，高级工程师会在自己的闲暇时刻进行Review。这或许是处理公司事务的好办法。其间一个优点是确立了相对一致的软件规划文明。但跟着公司规模扩大到更庞大的工程团队，维持集中式办法变得不可行。

此类Review所增加的首要价值在于它们为组织的集体经历供给了融入规划的机会。最重要的是，在Review阶段能够保证考虑到横切关注点（如可调查性、安全性和隐私）等方面。Review的首要价值并非问题被发现本身，而是这些问题相对前期地在开发生命周期内被发现，而且修正依然相对廉价。

施行和迭代

当工作发展到满足程度，有信心进一步Review不需求对规划进行严重更改时，便是开端施行的时候了。跟着方案与现实的碰撞，不可避免地会呈现缺陷、未处理的需求或许被证明错误的猜测，而且需求修正规划。强烈主张在这种状况下更新规划文档。作为一个经历规律：假如规划体系尚未发布，则绝对要更新文档。在实践中，咱们人类很擅长忘掉更新文件，而且由于其他实践原因，变更一般被阻隔到新文件中。这最终导致了一个相似于美国宪法带有一堆修正案而不是一份连接文档的状态。从原始文档链接到这些修正案能够极大地协助那些企图经过规划文档考古学来了解方针体系的不幸未来保护程序员们。

保护和学习

当谷歌工程师面临一个之前没有接触过的体系时，他们经常会问：“规划文档在哪里？”虽然规划文档（像一切文档相同）跟着时刻推移往往与现实脱节，但它们一般是了解体系创立背面思考办法最容易下手的途径。

作为作者，请你给自己一个便利，并在一两年后从头阅读你自己的规划文档。你做得对了什么？你做错了什么？假如今天要做出不同决议方案，你会怎么挑选？答复这些问题是作为一名工程师前进并改善软件规划技能的好办法。

结论

规划文档是在软件项目中处理最困难问题时取得清晰度和达成一致的好办法。它们能够节约金钱，由于避免了堕入编码死胡同而无法完结项目方针，而且能够经过前期调查来避免这种状况；但同时也需求花费时刻和金钱进行创立和Review。所以，在挑选项目时要正确！

在考虑编撰规划文档时，请思考以下几点：

您是否对正确的软件规划感到不确定，是否值得花费前期时刻来取得确定性？

相关地，是否有必要让资深工程师参与其间，即使他们或许无法Review每个代码更改，在规划方面能供给协助吗？

软件规划是否含糊甚至具有争议性，以至于在组织中达成一致将是有价值的？

我的团队是否有时会忘掉在规划中考虑隐私、安全、日志记载或其他横切关注点？

组织中对留传体系的高层次洞察力供给文档存在强烈需求吗？

假如您对以上3个或更多问题答复“是”，那么编撰一个规划文档很或许是开端下一个软件项目的好办法。

Reference

www.industrialempathy.com/posts/desig…