幾年前在 oreilly 看到一本叫 《living documentation》的書，可惜當時爛尾了。

最近圖靈出版了該書的中文翻譯版，才想起來有這么回事。。。正好最近有時間，把這個坑了幾年的東西給填上了。

簡單來說，這本書基本可以叫 living java doc(誤。我們可以先看看日常開發(fā)中會涉及到哪些文檔：

• 需求文檔

• 接口文檔

• 業(yè)務(wù)詞匯表文檔

• 模塊業(yè)務(wù)流程文檔

• 系統(tǒng)間交互文檔

• 系統(tǒng)架構(gòu)文檔

• 系統(tǒng)依賴文檔

• 發(fā)布文檔

• 示例文檔(tutorial)

• 項目進度文檔

• 案例文檔

• 匯報文檔

要寫的類型文檔還是不少的，無論哪種文檔，都與項目的代碼是脫節(jié)的。所以軟件行業(yè)以往的文檔編寫方式有很多缺點：

• 文檔易過時，因為與代碼是分開的，改了代碼忘改文檔是很正常的，代碼是新版本，而文檔是歷史版本

• 文檔誤導人，因為前一條，功能上的修改沒有反映到文檔上，讀文檔的人會被錯誤信息所誤導

• 多余的工作量，工程師在寫完代碼之后還要再去寫一遍文檔(也可能是先寫文檔后寫代碼)，基本是雙倍工作量

• 文檔的編寫工具無統(tǒng)一的規(guī)范，大家喜歡不停地嘗試新工具，從 word 到 markdown 到 asciidoc 到 notion

• 文檔與真實的代碼內(nèi)容是脫節(jié)的，比如在 DDD 中常講的業(yè)務(wù)詞匯表，在文檔與代碼中可能用的不是同一個詞，編碼和看文檔的時候需要腦內(nèi)額外做映射

為了克服這些缺點，這本書提出了一些讓代碼變 living 的方法。既然代碼和文檔分開使得兩者不易統(tǒng)一，那么我們就去追求把代碼與文檔寫在一起，并通過技術(shù)手段把文檔從代碼中生成出來。

live_doc

上面提到的幾種文檔，挨個來看看：

需求文檔

因為需求最終會變成 BDD 測試，所以可以直接用 BDD 測試來生成這些需求文檔。

詞匯表

用 DDD 來做業(yè)務(wù)的話，一般可以用一些一眼就能看出含義的詞對類型和接口做注解：@DomainService，@DomainEvent，@BusinessPolicy，@AbastractFactory，@Adapter，@BoundedContext，@ValueObject。

同時為了強調(diào)一些業(yè)務(wù)概念，也可以用一些自定義的詞匯，比如：@CoreConcept，@CoreBehavior，@StateMachine。

然后通過掃描代碼，就可以直接把項目中的上述概念抽出，每次代碼有更新，能夠自動生成業(yè)務(wù)的詞匯表。

自動接口文檔

這個應(yīng)該很多人也見過了，就是類似 swagger 的項目。框架做的好的企業(yè)基本也都會有基于類似 swagger 的手段來做自己的接口平臺(其實做的好的沒幾個)。下面是在 beego 中使用 swagger 的例子：

swagger

因為 Go 語言不支持 annotation，所以這些在注釋里寫的注解沒有語法層面的檢查和約束，這點上可能比那些支持的語言算是個弱勢。

業(yè)務(wù)流程文檔

在代碼中編寫相應(yīng)的流程節(jié)點和前后關(guān)聯(lián)節(jié)點：

business_process

通過掃描代碼生成文檔：

business_process2

跨系統(tǒng)的交互流程：

business_process3

掃描生成相應(yīng)的文檔，其實和前面的差不多：

business_process4

除了上面這些風格的注解，以前就已經(jīng)存在從文本生成文檔的手段，比如 plantuml，graphviz

plantuml

上圖這樣的 plantuml 的文本，本身就可以和代碼一起在同一個代碼倉庫中進行管理。

在一些業(yè)務(wù)邏輯中，涉及到難懂的邏輯，可以用 @Policy 或者 @BusinessConvention 來說明相應(yīng)的業(yè)務(wù)決策原因。

發(fā)布文檔

現(xiàn)在 Github 上的很多開源項目，已經(jīng)可以根據(jù) commit message 自動生成 release note 了。這歸功于其 commit message 本身就有一定的規(guī)范：

commit_msg

只要用簡單的 bash 腳本就可以將兩個版本之間的 commit message 進行匯總，并寫出完整規(guī)范的 release note。

國內(nèi)不少開源項目現(xiàn)在還是人肉寫 release note 的。

tutorial

新人入職需要看一些代碼范例，如果項目內(nèi)有寫的規(guī)范的代碼，可以專門挑出來作為例子：@Exemplar(“這個訂單流程是一個很好的 CQRS 學習示例”)。掃描代碼找到所有的 @Exemplar 注解就可以成為 tutorial 文檔了。

穩(wěn)定文檔

穩(wěn)定文檔指的是那些基本不怎么變動的文檔，這種文檔和代碼分開是可以接受的，為了使我們的文檔穩(wěn)定，應(yīng)該遵循一些基本的編寫原則，比如：

• 不要帶公司的那些容易變化的信息：公司名，子公司，品牌，商標等等

• 如果在文檔中附帶有鏈接，應(yīng)該從非穩(wěn)定文檔指向穩(wěn)定文檔，比如你可以從自己的 blog 貼一個 wikipedia 的鏈接，但是如果你去編輯 wiki 并粘貼了個人獨立 blog 的鏈接，那么可能就不太合適

• 不要復制粘貼，盡量用鏈接引用原有內(nèi)容

匯報文檔

如果是項目進度相關(guān)的內(nèi)容，可以用 @wip 或 @pending 之類的注解。

如果是給老板展示的案例，老板忙的沒時間，所以可以用 @keyexample 把這些需要單獨展示的案例摘出來，

如果是給新人學習的，除了前面說到的 tutorial，還可以有 @normalcase，@specs 等。

架構(gòu)文檔

一種是單模塊架構(gòu)，常見的是 DDD 中的六邊形架構(gòu)，可以引入 DDD 中的關(guān)鍵詞，并生成最終的文檔，比如 @HexagonalArchitecture.DomainModel，@Adapter，最終生成的文檔是下面這樣的：

hex

如果是跨系統(tǒng)的文檔，比如 CQRS 之類的，本身也是 Given(event)，When(cmd)，Then(output event) 的形式，所以用 BDD 可以生成這樣的文檔，前文有提到。

運行時文檔

作者認為 zipkin 和 dapper 這種 tracing 系統(tǒng)也是一種形式的文檔。服務(wù)發(fā)現(xiàn)系統(tǒng)中繪制出的服務(wù)依賴也是一種文檔。

聲明式配置

聲明系統(tǒng)配置、資源需求、依賴的，也可以生成文檔。

從這個意義上講 k8s 的 yaml 既是文檔，也是代碼。

架構(gòu)全景圖

當我們可以將所有文檔都通過掃描代碼生成之后，最好能夠?qū)⑦@些文檔管理在統(tǒng)一的架構(gòu)全景圖中，相應(yīng)的全景圖可能也可以用一些注解的輔助手段來生成，比如 @Layer(LayerType.INFRASTRUCTURE)，@Repository(aggregateRoot = Customer.class)。

總結(jié)

以上是生活随笔為你收集整理的活文档总结的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。