作者：Malte是Vercel的CTO。在此之前，Malte是負(fù)責(zé)谷歌搜索渲染的首席工程師，以及Search on Laptops, Tablets, 和Desktop的工程總監(jiān)。 譯者，許曉斌，現(xiàn)任阿里巴巴資深技術(shù)專家，《Maven實(shí)戰(zhàn)》作者。 Google 軟件工程文化中關(guān)鍵元素之一，是使用設(shè)計(jì)文檔來(lái)定義軟件設(shè)計(jì)。這些文檔通常不是非常正式，主要是軟件系統(tǒng)或應(yīng)用程序的作者在著手寫代碼之前編寫的。這些設(shè)計(jì)文檔記錄了 high-level 的實(shí)現(xiàn)策略和關(guān)鍵的設(shè)計(jì)決策，而后者重點(diǎn)描述了決策過程中思考的權(quán)衡。 作為軟件工程師，我們的工作并不是生產(chǎn)代碼本身，而是解決問題。非結(jié)構(gòu)化的文本，例如以設(shè)計(jì)文檔的形式，在項(xiàng)目早期或許是解決問題更適宜的工具。因?yàn)樵O(shè)計(jì)文檔可能更簡(jiǎn)明、更容易被理解，相比代碼能在更高的層面溝通問題及解決方案。 除了用作軟件設(shè)計(jì)的原始文檔記錄，設(shè)計(jì)文檔還在軟件研發(fā)生命周期中實(shí)現(xiàn)了下述功能： ●在修改成本還比較低的時(shí)候，盡早地識(shí)別設(shè)計(jì)缺陷。 ●在組織中圍繞設(shè)計(jì)達(dá)成共識(shí)。 ●確保橫切關(guān)注點(diǎn)（Cross-cutting concern）得到充分考慮。 ●在組織中傳播資深工程師的知識(shí)。 ●就設(shè)計(jì)決策形成組織記憶基礎(chǔ)。 ●成為軟件設(shè)計(jì)者技術(shù)資產(chǎn)中的一個(gè)摘要性制品。 1. 設(shè)計(jì)文檔的構(gòu)成 設(shè)計(jì)文檔是非正式的文檔，因此其內(nèi)容不需要遵循嚴(yán)格的準(zhǔn)則。因此首要原則就是：在特定的項(xiàng)目中，用任何最合理的形式編寫。 在此原則之外，Google 也建立了一種頗有效果的設(shè)計(jì)文檔結(jié)構(gòu)。 1.1 上下文和范圍（Context and scope） 這一小節(jié)給讀者展現(xiàn)一個(gè)有關(guān)這個(gè)系統(tǒng)在哪里被構(gòu)建，以及什么會(huì)被構(gòu)建的非常粗的概覽。這不是需求文檔。保持言簡(jiǎn)意賅！這里的目標(biāo)是讓讀者快速進(jìn)入狀態(tài)，可以假設(shè)讀者知道一些前置的知識(shí)，相關(guān)詳情可以給到鏈接。這一節(jié)內(nèi)容應(yīng)該完全關(guān)注在客觀的背景事實(shí)。 1.2 目標(biāo)和非目標(biāo)（Goals and non-goals） 給出一個(gè)簡(jiǎn)單的列表，講述系統(tǒng)的目標(biāo)是什么。有時(shí)候更重要的是講述非目標(biāo)是什么。注意，非目標(biāo)不是對(duì)目標(biāo)的否定，例如“系統(tǒng)不應(yīng)該 crash”，而是顯示地挑選出來(lái)的不是目標(biāo)的內(nèi)容。一個(gè)好的例子是 “遵循 ACID”，當(dāng)設(shè)計(jì)一個(gè)數(shù)據(jù)庫(kù)的時(shí)候，你必然想要知道這是目標(biāo)還是非目標(biāo)。進(jìn)一步的，你仍然可以選擇一個(gè)方案來(lái)實(shí)現(xiàn)非目標(biāo)，只要它不會(huì)給實(shí)現(xiàn)目標(biāo)帶來(lái)不必要的權(quán)衡。 1.3 實(shí)際設(shè)計(jì)（The actual design） 這一部分應(yīng)該以一個(gè)概述開頭，然后逐漸展開細(xì)節(jié)。 設(shè)計(jì)是文檔是在你設(shè)計(jì)軟件的過程中，記錄設(shè)計(jì)取舍的地方。應(yīng)該關(guān)注這些取舍，以產(chǎn)出一個(gè)具備長(zhǎng)期價(jià)值的文檔。具體就是，在既定的上下文（事實(shí)），目標(biāo)和非目標(biāo)（需求）下，設(shè)計(jì)文檔應(yīng)該提出解決方案，并闡明為什么某個(gè)特定的解決方案是滿足這些目標(biāo)的最佳方案。 相較于更為正式媒體形式，編寫文檔的意義在于可以用合適的方式靈活地表述手頭的問題集合。因此，如何描述設(shè)計(jì)并沒有顯式的指引。 話雖如此，對(duì)于大多數(shù)設(shè)計(jì)文檔來(lái)說(shuō)，一些最佳實(shí)踐和重復(fù)出現(xiàn)的主題還是有意義的： 1.3.1 系統(tǒng)上下文圖（System-context-diagram） 對(duì)于很多文檔來(lái)說(shuō)，系統(tǒng)上下文圖是很有用的。這類圖展示了當(dāng)前系統(tǒng)是更大技術(shù)圖景的一部分，能讓讀者在一個(gè)他們已經(jīng)熟悉的上下文環(huán)境中去理解新的設(shè)計(jì)。 1.3.2 APIs 如果設(shè)計(jì)的系統(tǒng)會(huì)暴露 API，那么草擬出 API 通常是好想法。不過，在大多數(shù)情況，我們應(yīng)該克制住把正式接口和數(shù)據(jù)定義復(fù)制粘貼到文檔中的沖動(dòng)，因?yàn)檫@么做會(huì)導(dǎo)致文檔過于冗長(zhǎng)，包含不必要的細(xì)節(jié)，并很快過期。相對(duì)應(yīng)的，我們應(yīng)當(dāng)關(guān)注和設(shè)計(jì)及取舍相關(guān)的那部分 API。 1.3.3 數(shù)據(jù)存儲(chǔ)（Data storage） 需要存儲(chǔ)系統(tǒng)的系統(tǒng)應(yīng)該討論數(shù)據(jù)是如何以何種形式，如何被存儲(chǔ)的。和前面描述 API 的建議一樣，基于相同的理由，應(yīng)該避免復(fù)制粘貼完整的 schema 定義，正確的做法是關(guān)注在那些和設(shè)計(jì)取舍相關(guān)的部分。 1.3.4 代碼和偽代碼（Code and pseudo-code） 設(shè)計(jì)文檔應(yīng)當(dāng)很少包含代碼或偽裝代碼，除非有一些情況需要描述新的算法。合理的做法是給到設(shè)計(jì)原型實(shí)現(xiàn)的鏈接。 1.3.5 約束條件（Degree of constraint） 軟件設(shè)計(jì)形態(tài)（因此設(shè)計(jì)文檔）的主要影響因素是解決方案空間（solution space）中的約束條件。 一個(gè)方向的極端情況是 “綠地軟件項(xiàng)目（greenfield）”，在這種情況下我們知道所有的目標(biāo)，解決方案只要是合理的，沒什么限制。這樣的文檔可能就會(huì)顯得很寬泛，但是也應(yīng)該快速定義一組規(guī)則，以便讓大家盡快把目光收斂到一組可控的解決方案中。 另一個(gè)方向的極端情況是，所有可能的解決方案都被定義得很清楚了，但是如何把它們結(jié)合起來(lái)以達(dá)成目標(biāo)，卻毫不清晰。這往往是因?yàn)檫z留系統(tǒng)難以改動(dòng)，或者遺留系統(tǒng)不是被設(shè)計(jì)用來(lái)解決當(dāng)前所面臨的問題的，又或者是一個(gè)類庫(kù)的設(shè)計(jì)要求我們?cè)谒乃拗骶幊陶Z(yǔ)言限制下工作。 在這種情況下，你或許可以遍歷所有可行的簡(jiǎn)單方法，但更需要?jiǎng)?chuàng)新地把所有這些方法整合起來(lái)以完成目標(biāo)。也許存在多種方案，每一種方案都不是特別出色的，因此文檔應(yīng)該關(guān)注在如何從已經(jīng)識(shí)別的各項(xiàng)取舍中，選擇最合適的方案。 1.4 候選設(shè)計(jì)（Alternatives considered） 這一小節(jié)列出那些同樣可以實(shí)現(xiàn)類似產(chǎn)出的可選設(shè)計(jì)。這里關(guān)注的應(yīng)該是各種方案各自的取舍，以及這些取舍的對(duì)比如何引向最終的設(shè)計(jì) —— 文檔的核心主題。 雖然描述候選設(shè)計(jì)可以簡(jiǎn)潔一些，但是這一小節(jié)實(shí)際上非常核心的，因?yàn)檫@里非常清晰地展示了，在給定的項(xiàng)目目標(biāo)和所有可選方案下，為什么選擇了最終方案，在給定目標(biāo)下權(quán)衡的判斷是如何做出的，而這正是文檔的讀者所關(guān)注的核心。 1.5 橫切關(guān)注點(diǎn)（Cross-cutting Concerns） 在這里組織可以確保一些橫切關(guān)注點(diǎn)如安全，隱私，可觀測(cè)性，總是被考慮到。這部分內(nèi)容通常相對(duì)較短，只是用來(lái)解釋設(shè)計(jì)會(huì)如何影響到橫切關(guān)注點(diǎn)，以及相關(guān)影響如何得到解決。團(tuán)隊(duì)?wèi)?yīng)該標(biāo)準(zhǔn)化在他們場(chǎng)景下的關(guān)注點(diǎn)。 例如，由于隱私非常重要，Google 的項(xiàng)目就必須寫一個(gè)專門的隱私設(shè)計(jì)文檔，這個(gè)文檔會(huì)別專門用來(lái) Review 隱私和安全。雖然 Review 只要在項(xiàng)目啟動(dòng)前完成，但通常最好是盡早讓隱私和安全團(tuán)隊(duì)介入，確保設(shè)計(jì)從一開始就重視他們的意見。關(guān)于這部分內(nèi)容更專門的細(xì)節(jié)，核心文檔不一定要全部包含，有時(shí)候給到這些專門文檔的引用即可。 1.6 設(shè)計(jì)文檔的長(zhǎng)度（The length of a design doc） 設(shè)計(jì)文檔應(yīng)該具備充分的細(xì)節(jié)，但同時(shí)足夠簡(jiǎn)短以能夠被忙碌的人閱讀。對(duì)于一個(gè)大型項(xiàng)目來(lái)說(shuō)，最佳的長(zhǎng)度似乎是 10 到 20 頁(yè)。如果你的內(nèi)容超過這個(gè)大小，更合理的做法可能是把這個(gè)問題劃分成更易管理的子問題。當(dāng)然，需要注意的是，編寫 1-3 頁(yè)的“迷你設(shè)計(jì)文檔”完全是可能的。這類文檔對(duì)于敏捷項(xiàng)目中的增量改進(jìn)或者子任務(wù)尤其有用 —— 但你仍然需要和編寫長(zhǎng)文檔一樣執(zhí)行一樣的步驟，區(qū)別只是讓內(nèi)容更精煉，并且只關(guān)注有限的問題集合。 2. 什么時(shí)候不要編寫設(shè)計(jì)文檔（When not to write a design doc） 編寫設(shè)計(jì)文檔是需要成本的。關(guān)于是否編寫設(shè)計(jì)文檔的決定，實(shí)際上是在做權(quán)衡。權(quán)衡的一邊是圍繞設(shè)計(jì)、文檔、高層評(píng)審等工作形成組織共識(shí)的益處，權(quán)衡的另一邊是這塊工作投入的精力成本。決策的核心在于設(shè)計(jì)問題的解決方案是否模糊 —— 這往往是因?yàn)閱栴}復(fù)雜度，或者解決方案的復(fù)雜度引起的（或者兩者皆有）。如果不存在這個(gè)問題，那么走一個(gè)設(shè)計(jì)文檔編寫的流程價(jià)值就有限。 設(shè)計(jì)文檔可能沒有必要的一個(gè)明顯征兆是：設(shè)計(jì)文檔實(shí)際上是實(shí)現(xiàn)手冊(cè)。如果文檔基本上說(shuō)的是“這是我們將如何實(shí)現(xiàn)之”，而沒有深入討論取舍、可選方案、沒有解釋決策（或者說(shuō)解決方案太明顯了以致于沒什么取舍可討論），那么很有可能直接編寫真實(shí)代碼是更好的選擇。 最后，創(chuàng)建和評(píng)審設(shè)計(jì)文檔的投入可能與快速制作原型并迭代理念并不相容。但是大多數(shù)軟件項(xiàng)目都是有一組實(shí)際上已知的問題。擁抱敏捷方法不應(yīng)該成為不花時(shí)間去尋找已知問題正確解決方案的借口。此外，原型本身可能就是創(chuàng)建設(shè)計(jì)文檔過程的一部分?！拔以囘^了，這么做可行” 就是選擇一種設(shè)計(jì)最好的論據(jù)之一。 3. 設(shè)計(jì)文檔的生命周期（The design doc lifecycle） 一份設(shè)計(jì)文檔的生命周期包括如下階段： 1.創(chuàng)建和快速迭代 2.審查（可能有多輪） 3.實(shí)現(xiàn)和迭代 4.維護(hù)和學(xué)習(xí) 3.1 創(chuàng)建和快速迭代（Creation and rapic iteration） 你編寫文檔，有時(shí)候是和幾個(gè)合作者一起編寫。 這一階段快速演進(jìn)成為快速迭代的時(shí)期，文檔被分享給一些同事，他們擁有關(guān)于問題空間（problem space）的最多的知識(shí)（通常屬于同一個(gè)團(tuán)隊(duì)），通過他們不斷澄清問題并提出建議，文檔逐漸形成第一個(gè)相對(duì)穩(wěn)定的版本。 你會(huì)發(fā)現(xiàn)很多工程師和團(tuán)隊(duì)更偏向于使用版本控制和代碼審查工具來(lái)管理文檔，但是 Google 的大多數(shù)文檔是使用 Google Docs 創(chuàng)建的，并重度使用了協(xié)作特性。 3.2 評(píng)審（Review） 在評(píng)審階段，設(shè)計(jì)文檔被分享給原始作者和緊密協(xié)作者之外更廣范的一批受眾。評(píng)審可以給文檔增加很多價(jià)值，但是也有可能是危險(xiǎn)的投入成本陷阱，因此要明智對(duì)待。 評(píng)審可以有很多形式：最輕量的版本就是簡(jiǎn)單把文檔發(fā)給更大范圍的團(tuán)隊(duì)，讓大伙有機(jī)會(huì)可以看一眼。隨著而來(lái)的討論主要就發(fā)生在文檔的評(píng)論區(qū)。而形式較重的評(píng)審，就是發(fā)起正式的設(shè)計(jì)文檔評(píng)審會(huì)議，在會(huì)議中作者面向通常是較為資深的工程師聽眾演示文檔（通常是專門的演示）。Google 有很多團(tuán)隊(duì)為此目的排了周期性的會(huì)議，工程師可以注冊(cè)用來(lái)發(fā)起設(shè)計(jì)評(píng)審。自然的，等待此類會(huì)議來(lái)評(píng)審設(shè)計(jì)文檔會(huì)大幅降低研發(fā)速度。工程師可以通過直接向同事獲取最關(guān)鍵的反饋，同時(shí)也不阻塞更廣泛的評(píng)審，進(jìn)而降低這一風(fēng)險(xiǎn)。 當(dāng) Google 是一個(gè)小一些的公司的時(shí)候，大家習(xí)慣上會(huì)把設(shè)計(jì)發(fā)到一個(gè)中心的郵件列表中，在這里資深的工程師會(huì)抽空進(jìn)行評(píng)審。這種方式對(duì)公司來(lái)說(shuō)可能就不錯(cuò)。這種方式一大好處是，它在整個(gè)公司層面建立了一種相對(duì)一致的軟件設(shè)計(jì)文化。但是隨著公司逐漸增長(zhǎng)細(xì)形成一個(gè)較大的工程師團(tuán)隊(duì)，維護(hù)這種中心化的方法就不可行了。 設(shè)計(jì)評(píng)審增加的主要價(jià)值是，它形成了一個(gè)讓組織的綜合經(jīng)驗(yàn)可以融合到設(shè)計(jì)中的機(jī)會(huì)。如何讓設(shè)計(jì)能夠充分考慮橫切關(guān)注點(diǎn)如可觀測(cè)性、安全性、以及隱私，這一點(diǎn)就能夠非常一致地在評(píng)審階段得到保障。評(píng)審的主要價(jià)值不是問題被發(fā)現(xiàn)本身，而是讓問題在軟件研發(fā)階段相對(duì)早期的時(shí)候，也就是修復(fù)成本相對(duì)較低的時(shí)候被發(fā)現(xiàn)。 3.3 實(shí)現(xiàn)和迭代（Implementation and iteration） 當(dāng)事情獲得了充分的進(jìn)展，看起來(lái)進(jìn)一步的評(píng)審不太會(huì)要求設(shè)計(jì)做重大的改變，那就是時(shí)候開始實(shí)現(xiàn)了。當(dāng)計(jì)劃和現(xiàn)實(shí)沖突，不可避免的會(huì)發(fā)現(xiàn)設(shè)計(jì)的缺陷，未被充分考慮的需求，或者基于經(jīng)驗(yàn)的推測(cè)實(shí)際上錯(cuò)誤的，進(jìn)而發(fā)現(xiàn)需要對(duì)設(shè)計(jì)做修改。在這種情況下強(qiáng)烈推薦更新設(shè)計(jì)文檔，一般說(shuō)來(lái)：如果系統(tǒng)還沒有上線，那么很確定應(yīng)該更新文檔。在實(shí)踐中，我們普通人在更新文檔方面都做得不好，以及因?yàn)橐恍┢渌膶?shí)際因素，更新還通常會(huì)落到新的獨(dú)立的文檔中去。這就導(dǎo)致了一種近似美國(guó)憲法的最終態(tài)：有一堆修正案，而非一份一致的文檔。對(duì)于將來(lái)維護(hù)系統(tǒng)的可憐程序員來(lái)說(shuō)，當(dāng)他們像考古學(xué)家一樣翻閱歷史設(shè)計(jì)文檔，去試圖理解目標(biāo)系統(tǒng)的時(shí)候，原始文檔中給出這些“修正案”的鏈接會(huì)非常有幫助。 3.4 維護(hù)和學(xué)習(xí)（Maintenance and learning） 當(dāng) Google 工程師首次接觸一個(gè)系統(tǒng)的時(shí)候，他們的第一個(gè)問題通常是“設(shè)計(jì)文檔在哪里？”。雖然說(shuō)設(shè)計(jì)文檔和所有其他文檔一樣，都會(huì)隨著時(shí)間的流逝變得和現(xiàn)實(shí)不一致，但它們依舊是學(xué)習(xí)系統(tǒng)在創(chuàng)建之初其背后思考的最佳起步材料。 作為作者，從為自己著想的角度考慮，可以在一兩年后重新閱讀自己的設(shè)計(jì)文檔。你哪里做對(duì)了？哪里做錯(cuò)了？在今天來(lái)看你會(huì)做哪些不同的決策？對(duì)于工程師來(lái)說(shuō)，回答這些問題是一種絕佳的提升軟件設(shè)計(jì)能力和自我進(jìn)步的方式。 4. 結(jié)論（Conclusions） 在軟件項(xiàng)目中，圍繞解決最難的問題，設(shè)計(jì)文檔是一種獲得清晰度以并達(dá)成共識(shí)的絕佳方法。設(shè)計(jì)文檔可以節(jié)省金錢，因?yàn)樵谇捌谧銐虻恼{(diào)研可以幫助避免過早就進(jìn)入編碼細(xì)節(jié)卻未能完成項(xiàng)目目標(biāo)；設(shè)計(jì)文檔又花費(fèi)金錢，因?yàn)榫帉懞蛯彶槲臋n消耗時(shí)間。因此，在你項(xiàng)目中明智地做出選擇。 在考慮是否編寫設(shè)計(jì)文檔的時(shí)候，思考如下問題： ●你是否對(duì)正確軟件設(shè)計(jì)不確信？在前期消耗時(shí)間來(lái)獲取確定性是否合理？ ●在設(shè)計(jì)階段引入相關(guān)的資深工程師是否有幫助？他們可能沒有時(shí)間審查所有代碼。 ●軟件設(shè)計(jì)是否是模糊的，甚至是有爭(zhēng)議的？因此圍繞這一問題在組織層面達(dá)成共識(shí)會(huì)很有價(jià)值？ ●我團(tuán)隊(duì)是否有時(shí)候會(huì)在設(shè)計(jì)中忘記考慮隱私、安全、日志或者其他橫切關(guān)注點(diǎn)？ ●在組織中是否非常需要遺留系統(tǒng)設(shè)計(jì)的文檔？這樣可以讓大家在 high-level 快速了解系統(tǒng)。 如果對(duì)于上述的問題你有三個(gè)或更多“是”的回答，那么在你開始下一個(gè)軟件項(xiàng)目的時(shí)候，設(shè)計(jì)文檔大概率是個(gè)不錯(cuò)的方法。