不要嘗試同步代碼和設計文檔

不要嘗試同步代碼和設計文檔，這是我在這麼多年設計工作中的一個核心體會。很多的工程失敗，或者說工程方法的失敗，都源自在這個問題上的「過猶不及」。或者引申一點說，很多工程方法的失敗，其實都源自「過猶不及」。

設計文檔不是我們的交付，我們的交付是代碼，所以，我們所有的行為，都是為了保證代碼交付的完好，不是設計文檔交付的完好。當我們越過了設計階段，最終構成代碼，保證代碼和設計一致，這個投資回報率就變得很低了，所以，一旦我們形成了代碼，基本上我們就不應該更新設計文檔了。

請注意，這裡說的是「設計文檔」，不是說「用戶手冊」，「用戶手冊」是交付的一部分，「設計文檔」是中間過程文檔，兩者和代碼的同步成本也不同。有時（很多時候），我們會把「用戶手冊」作為「設計文檔」的一部分，說明這一點是有必要的。

是的，我知道很多客戶，管理者，架構師，都喜歡要求保持「代碼與文檔一致」，因為這個「戰略邏輯簡單」，是啊，代碼和設計文檔一致，後來的維護者根據這個文檔理解這個代碼，這多麼好？這一點恰恰詮釋了《道德經》中說的，高以下為基，貴以賤為本。做管理的，做架構的，關鍵問題根本不在於「是否有道理」，而是能否實現最高投資回報率。但拜託你們真的去做做一個生長期的軟體的文檔和代碼同步好不好？修改代碼的工程成本是很高的好不好？只要你發一個命令下來，你要什麼都有人給你做，問題是你拿到了足夠的回報了嗎？要求兩者同步，會導致很多修改被綁死在文檔同步的工作量上，不是按如何讓軟體更好生長來修改軟體，而是按怎麼才能「少修改文檔」來修改軟體，這相當於自己給自己綁著跳舞，跳得好就有怪了。

我前面說，很多工程方法的失敗，在於「過猶不及」，就是這個原因。很多項目一開始雄心壯志，架構師信誓旦旦說要保持「文檔和軟體同步」，後面工程工作量實在撐不住了，這些人就又反轉，變成「文檔沒有什麼用，代碼即文檔」了。但天之道，下者舉之，高者抑之。天之道是要「准」的，不是你賭氣拚命用力就可以的。

保持「文檔和軟體同步」帶來的收益其實是非常有限的，而且會導致修改文檔的時候不重點考慮如何進行設計才是最優，實際上偏離了設計路線。而且很大程度上，還會導致文檔的結構變得臃腫而不聚焦，邏輯鏈分散。我們寫設計文檔，本來就是因為代碼非常複雜，不利於腦子對整體邏輯進行控制。如果我們控制文檔像控制代碼一樣，很容易也陷入到代碼控制本身的問題上。

所以，我更建議兩者分開管理，不需要保持兩者一致。文檔就是在翻譯為代碼前的一個設計的Snapshot，一旦完成了Review並開始編碼，就可以忘掉它（不反對為了交流的方便，有時去做一點更新，但那個不是核心策略）。後續如果代碼更新得很大，可以寫補充文檔，說明經過這段時間的維護，有那些地方的理念發生的變化。

而這樣的一個文檔序列，其實在大部分時候比一個「完美的」全局文檔更有用。我們的軟體本來就是「生長」出來的，我們變成現在這個形態，是因為中間發生的那些事情，不是「原始的理念」。看到一個個的Snapshot，反而更容易理解一個軟體的設計理念，這個文檔「序列」本身，才是更清楚的設計文檔。這才是「設計文檔」該有的存在形式。