無痛苦的軟體維護——文檔和代碼

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

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，以達到知識的交流和維護的便利。代碼是最重要的溝通語言。在代碼說不清楚的情況下，文檔也是必須的。