一星期8天

程序維護的時候經常遇到兩個困難：

1、不知道這段代碼是實現什么功能的（code —— function）；
2、不知道這個功能是實現什么需求的（function —— business）。

解決第一個問題是比較容易的，大家都是搞技術的，一頭扎進代碼里去，看上幾十分鐘，通常就能明白：原來這段代碼是從數據庫里面找到前三個月一直處于停機狀態的號碼，然后把這些號碼放到一個叫做QUIT_USER的數據表里面去。

第二個問題就難了，經常從代碼中是看不出來的，于是項目開發的過程中就制造出來了大量的文檔，來幫助開發者交流這個問題，也讓將來維護這段代碼的人知道這個知識。

我們可以查找與這段代碼相關的文檔，文檔上說：這段代碼把停機三個月的號碼放到一個叫做QUIT_USER的表里面，一個月以后，這些號碼由另外一段代碼拿去篩一下，把最近剛交了費用的號碼刪掉，剩下的用戶做退網，號碼回收，凍結半年以后可以重新使用。

令人難過的是，維護程序的人很難有幸看到如此貼心的文檔。他們查了半天經常看到的是：這段代碼按照xxx的規則，從xxx表中查詢數據，然后再把結果的數據經過xxx的處理，放到QUIT_USER表里面，over。你仍然不知道他到底是在做什么。

并且，文檔與代碼的同步也是一個難題。不僅是文檔，即使是代碼中的注釋，誰又能保證他真實的描述了系統的運行方式呢？時間緊張、錯誤的理解都可能造成文檔與實際情況不同。我們假定寫文檔和寫注釋的人是認真的、不犯錯誤的，他們也必須忽略一些細節，他們不能什么都寫上去。而他們忽略的細節很有可能為以后的維護帶來麻煩。

很多項目都有這個問題：business和function是脫節的。熟悉客戶業務的人設計出一系列的功能點，這些功能點按照最初的設計是可以完成客戶的業務的。然后這些功能點就拿到開發人員那里去造出來。而開發人員對用戶的business其實是不了解的，他們的眼中只有function。到了維護的時候，business發生了變化，function重新設計。經常是經過一番修改，程序按照開發人員的思路運行良好，但是用戶卻一個勁的搖頭：“不不，不是這樣的，我們要的是這個……”程序到底解決了哪些business，已經成了一個迷。

什么東西可以最準確的描述程序的運行過程呢？只有代碼本身。并且，經過精心設計的代碼也能很好的對business進行描述。比如剛才說的那件事情，一段代碼把號碼放到QUIT_USER里面，另一段代碼從這里面篩除一些號碼做退網。這兩個function其實在business方面都屬于一個點，那么就應該讓這兩段代碼寫在一起，封裝起來——這就是高內聚。并且這一段代碼內部的操作應該與其他的功能沒有任何關系，除非那個功能與這兩個功能具有business上的共同點，別的代碼應該不知道QUIT_USER是個什么東西——這就是低耦合。

一個項目的代碼，總是由大尺度的構思開始的，然后越來越貼近細節，牽涉越來越多的技術。但是寫到最后，代碼應該回到對business本身的描述。代碼越貼近business，對維護的幫助就越大。

我現在要維護一個公司的財務管理程序，我想知道職員的工資里面是不是已經計入了他們的個人所得稅。我找到Account（會計），他應該有一個方法，每個月運行一次，把Salery發給Emplyee，我找到這個Salery，看到里面已經包含了Tax。我發現Account計算這個Tax的時候使用了一個Stratagy（策略）。他調用的是一個名叫Stratagy1998的策略，以800元作為基數計算個人所得稅。現在這個基數已經發生了變化，于是我修改這個Stratagy1998、或者替換掉一個新的Stratagy2005。這樣就完成了一次變更。并且我知道這樣修改不可能影響到business不相關的東西。

文檔永遠只能表示“某時某刻我們曾經這樣想過”，讓文檔時刻保持與代碼的同步是不實際的。要想知道“現在程序是怎樣運行的”，只有代碼能夠告訴我們。文檔應該配合代碼，做代碼不能做的事情，配合把business說清楚。而不應該與代碼發生沖突。

文檔應該去描述代碼無法說清楚的事情上，比如用戶的工作場景、某個需求是由誰提出來的、大尺度的程序設計、重要對象的運行時序、系統安裝手冊。比如下面這個圖，他清楚的說明了“銷戶”這個行為在整體的需求中處于什么地位。這樣的東西用代碼說清楚是比較費力的。當然用代碼也能說清楚，比如可以使用State - Action模式，但是總歸不如一張圖表示的這么清楚。



XP和Agile方法所提倡的“盡量少寫文檔”，就是基于這樣一種設計理念：盡量的用代碼和測試代碼來描述business，以達到知識的交流和維護的便利。代碼是最重要的溝通語言。在代碼說不清楚的情況下，文檔也是必須的。