新一篇: 思考詳細設計——maillist中的討論
ai92 2006-8-2
設計在軟體開發中扮演的角色，相信大家都很清楚。設計的好壞直接影響著軟體產出的質量。設計一般分為架構設計（概要設計）和詳細設計。架構設計主要從系統整體上來考慮使用什麼樣的架構、如何劃分模組以及制定模組間的通訊規則。因此架構設計從規模或者粒度上都比較好把握。而詳細設計則與架構設計不同，它的工作量通常不小而且粒度不好把握。所以詳細設計往往實踐的不是很成功，要麼流於形式，要麼直接被pass掉……。
下面是我對詳細設計的一點思考，其間alexwei12、chinakite給出了很好的建議，並將經驗分享給我。
設計之痛——編寫文件
詳細設計作為軟體開發中不可缺少的過程，理應由輸入、活動、輸出這三部分組成。最重要的部分當然就是「活動」這乙個環節，在這一環節裡面，設計人員根據需求和架構設計構思可行的解決方案。而「輸出」部分就是這一節要討論的詳細設計文件。我認為詳細設計產生文件的主要作用大抵是為了和實現人員或者任務交接人員進行「溝通」，使別人明白你的設計意圖和設計方式。當然它也有著在設計時理清思路的作用。
gresham法則如是說：「程式化的活動容易將非程式化的活動驅逐出去」。詳細設計文件的編寫的確很容易占用原本用於尋找解決方案的「活動」時間，而使得真正用於設計的時間變得急促。這種本末倒置的現象是如此的普遍，似乎成了合情合理的了。
造成這種局面的原因大概就是因為編寫文件的痛苦和難以維護。
在軟體過程普遍得到重視的今天，每個公司大多都有乙個所謂的過程財富庫。財富庫中都有一些所謂的模版來統一文件編撰的格式。而其中的「詳細設計模版」大抵是這個樣子的：總的類結構圖，總體說明，每個類的定義，每個屬性的定義，每個方法的定義，每個引數的定義，返回值的定義，甚至注釋的定義、偽**……。詳細的可以稱作**的文件版。坦白的講，編寫這樣的文件是件很痛苦的事。
如果你能做到一次設計即可完美的將需求實現到**中去。那麼費一次勁將《詳細設計說明書》編寫完成，也可以算是一件事後很愉快、很有成就感的工作。但是需求的變更、設計的險惡以及自身能力的限制讓你總是與完美保持距離。而這時，修改和同步《詳細設計說明書》就變成了噩夢之旅。當然，你也可以選擇放棄，於是這些文件就變成了廢紙甚至誤導其他人的陷阱。
再者，這樣編寫出來的文件並不比**好看多少，特別是當文件的厚度達到一定程度之後。很難想象乙個可憐的人抱著幾百上千頁的《詳細設計說明書》進行「溝通」的場景。何況習慣於閱讀**的人是不會想去閱讀乙個沒有任何ide支援、很可能存在錯誤甚至已經過時的**文件版的東西。
那到底如何來編寫文件呢？是不是這根本就沒有意義？
解決這個惱人的問題，似乎有以下幾種方式：
2. 使用圖形代替《詳細設計說明書》。我認為在設計中理清思路和表達理念的最佳方式還是抽象的圖形（而為了統一大家溝通的語言，制定乙個標準表達方式還是不錯的主意，而uml就是乙個現成的不錯選擇）。用能夠簡單、清晰的表達設計藍圖的圖形來整理你的設計思緒，並作為「溝通」語言傳遞給實現人員或者任務交接人員。注意，是簡單、清晰的圖形，而不是面面俱到、事無鉅細的圖形。
3. 使用api doc代替《詳細設計說明書》。花了大力氣來編寫乙份沒有作用的文件，不如將這份精力投入到編寫好的高質量的**上去。事實上，沒有任何比源**更詳細、更易讀的文件了，那麼就將你的詳細設計作為注釋寫到**中吧。
4. 2、3結合使用。
5. 在專案最後編寫文件。如果無論如何都要上交乙份《詳細設計說明書》的話，那就把這個任務留在專案最後吧，因為這時設計基本趨於成熟，編寫文件的痛苦可以降到最低。
也許有人會提到文件裁剪、設計評審等有效緩解設計之痛的方法。但是在我見過的公司裡面，這些環節都形同虛設（將別人表面的東西拿來做重要內容，又將別人重要的東西拿來做表面功夫）。這又應了gresham法則。
重在過程，把握粒度
詳細設計是乙個經驗與智慧型並重的創作過程，詳細設計是技術更是藝術。看乙個人的詳細設計成果，可以很好的檢驗他的技術功底和實戰經驗；全面參與一次詳細設計過程，則可以很好的鍛鍊自身能力與團隊意識。它不僅僅存在於預先設計階段，而且也存在於編碼階段。這是乙個逐步細化、深入的過程。
在設計階段，詳細設計到什麼程度才算好呢？哪些應該放到編碼階段中去細化呢？
rup中講究裁剪，詳細設計的粒度同樣也需要裁剪，有時詳細設計會細化到可以生成**，而有時詳細設計則僅是幾張圖紙（又說了句實在的廢話）。下面是來自chinakite對如何把握詳細設計粒度總結的經驗：
1. 看工期。如果工期非常緊，則簡化到概要設計的程度；正常情況細化到類的結構，關鍵點——比如使用者認證框架執行機制細化到方法及使用順序。如果工期寬裕的話，你不仿做的詳細些。團隊專案就這特點，跟自己程式設計不一樣，你必須為你的專案負責。
2. 看功能。如果很複雜的功能，比如我原來做的許可權部份，我覺得很複雜，這部分已經不只靠uml就能說明白了，除了詳細的uml外還要加上doc文件說明。如果複雜程度一般，比如乙個使用者的許可權設定，細化到類一層就足夠了，序列圖在這時相對重要，因為這能表明你的邏輯，類圖並不很重要，可畫不可不畫，以後能找到能看懂就行。複雜程度很低，就不需要做，比如就簡單地向資料庫寫條記錄，做了就是在無聊。
3. 看人員水平。如果大家水平都較高，那麼能簡化則簡化，如果水平一般或以下，最好還是做得詳細些吧，不然將來有得頭疼的。
4. 看業務層次。越底層的東西對詳細設計的要求就越高，要時刻記著這些東西不只是你乙個人看的，是給所有你的受眾看的。不要以為你給了介面他們就會滿意了，有時他們更想知道你的想法以及對你的想法提出建議，上層的相對簡化。
當然，你可能還要結合實際專案的規模、模組權重等等因素做出適當的折中和取捨。完成了預先設計階段的任務以後，在實現階段我們可以通過重構、**走查等方式來進一步細化設計，最終得到乙個讓人感到滿意和清爽的設計結果。
設計模式思考
高層模組不應該依賴於底層模組，應該在他們之間建立乙個抽象層，來實現可替換的底層，不變的介面層。這個是物件導向的更高境界了，面向介面程式設計。上層和下層通過唯一途徑聯絡就是介面，這有點類似與作業系統和軟體和硬體之間的關係，他們的聯絡也是通過能夠接觸到那一層介面來實現。可以說我們只需知道介面就能完成呼叫...
RESTful API 設計思考
restful 是目前最流行的 api 設計規範，用於 web 資料介面的設計。它的大原則容易把握，但是細節不容易做對。本文總結 restful 的設計細節，介紹如何設計出易於理解和使用的 api。url 設計 1.1 動詞 賓語 restful 的核心思想就是，客戶端發出的資料操作指令都是 動詞 ...
詳細設計文件
如上圖，可以看到詳細設計文件是，瀑布模型 中承上啟下的乙個關鍵環節，在做好需求分析和軟體架構之後，寫好詳細設計文件就意味可以進行編碼了。由此，可以看到詳細設計文件有三個作用 1，為具體編碼環節做好鋪墊與設計，從而指導編碼工作 2，提供測試所需文件參考 3，可作為理解編碼的參考文件。詳細設計的主要任務...