日趨一日，程式設計師能夠在更少的時間內完成更多的事情。使用今日的高階程式語言，開發環境，工具和「快速應用開發」思想，程式設計師和經理都已經習慣於急速的開發周期。今日的程式設計師更傾向於直接跳入到編碼之中，害怕花費在非編碼工作中的每一小時，都會導致專案截止日期前的週末多加乙個小時班。
編碼之前做設計這一過程已經變得過時了，將設計文件化就更罕見了。很多程式設計師從來沒有寫過設計文件，面對要寫設計文件這一想法都畏縮不前。即使被要求寫，通常來說也只是產出了一大堆的互動圖和類圖，這些圖表大多沒有表達程式設計師在設計階段的思考過程。本文將簡明扼要地討論如何不用特殊工具寫出有效的設計文件，同時無需了解uml。文中也會談到為什麼乙個好的設計文件是在開始乙個新專案時，程式設計師可以擁有的最有價值的工具之一。
為什麼要寫設計文件？
一篇設計文件是乙個你同他人交流的工具，來闡明你的設計決策是什麼以及為什麼你的決策是好的。不要擔心你的設計不符合uml標準，也不要擔心你沒有使用特殊的建模工具來建立它。決定你的設計文件優劣的最大因素，是它是否清晰的解釋了你的意圖。
然而這引出了乙個問題，為了傳達設計決策，你需要去考慮聽眾是誰。乙個程式設計師同行會理解為什麼乙個精心設計的類抽象是乙個好的設計，然而你的經理可能不會。因為你的程式設計師同行和你的經理對於什麼是好設計有不同的概念，所以需要有兩份設計文件；乙份給同行，乙份給經理。當你開始你的專案時，每份文件為了不一樣但有同等價值的目標服務。
這看起來是過多的工作，但它實際上不是。本文將向你展示如何通過文件的重用來完成它。
哪些因素造就了乙個好的設計？
通常，如果乙個設計通過有意義的方式實現了需求，它就被認為是好的。如果設計的任意乙個方面拿不出正當理由，那麼它可能就需要被重新評估。很多程式設計師試圖在他們的設計中包含進設計模式，這常常只會增加不必要的複雜性。你需要能列舉出至少乙個令人信服的與需求相關的理由，去解釋為什麼要做出這樣的設計決策。然後這些理由也需要被文件化。如果你面對乙個設計決策無法拿出乙個清晰的理由，那麼它可能沒有給你的設計增加任何價值。
圖表是將你的設計視覺化的偉大工具，但它們無法傳達你的設計決定背後的動機。這就是為什麼關鍵的是，讓你的圖表補充你的設計文件，而不是充當設計文件。
另外乙個關鍵點是，要記錄你的設計決策帶來的好處。通過這樣做，其它閱讀你的文件的人將能理解他們所能獲得的價值。同理，任何關聯的風險也要被記錄下來。多數情況下，其它程式設計師可能面對過相同的風險，可能會有你沒有想過的有用的觀點或者方法。通過列出這些條目，你也讓他人去思考潛在的風險。組員常常能看到當你在設計時無法覺察到的陷阱。重組織圖表中的框圖是很簡單的，但如果編碼過程中發現假定不成立，或者踩中了乙個沒有預見到的陷阱而需要重寫幾百行**，則要困難得多。乙個好的設計文件最小化了意料之外的混亂，因為它在編碼前就將這些困難點定位出來了。
最後，文件給你，你的經理和你的團隊提供通用的語彙，來討論這個專案。設計文件對於經理來說是有用的工具，因為它提供了乙個深入專案之中的視野，而通常來說他們沒有專門的技術知識去看到這些。通過列出好處，你給你的經理提供了切實的條目來描述為什麼你的設計是可靠的。通過在開發之前記錄你設計的風險，你將那些風險的責任傳遞給你的經理了，而那是他們應該承擔的。
還有，設計文件是乙份你，你的經理和你的團隊之間的契約。當你記錄下你的假定，決策，風險等等時，你給其它人乙個機會去說：「是的，這就是我所期待的。」一旦你的文件經過了設計階段，它就是乙個基線，用來在專案範圍內控制變化。顯然，需求將會時不時地改變，但有乙個基線文件，你就有權力說專案內的所有變動都不是由於對需求的誤解造成的。
寫給程式設計師同行的文件
開發者設計文件的目標是確保你的想法是有效的，你的方法可以和別人正在做的工作相互配合。如果開發者之間不交流他們的計畫，那麼在不同的模組或者類開始互動時，災難一定會爆發。以下條目描述了寫這一型別文件的通用指南：
第一節 - 陳述你的專案/子系統的目標：在這一節中，寫幾個段落來描述你的專案或者子系統做了什麼。它試**決的問題是什麼？為什麼它需要存在？誰將會使用它？通過回答這些問題，你建立起設計的範圍。如果你發現在這一節中要寫出幾個段落很困難，那你可能還沒有將問題域理解到你需要的程度。如果你不能將你的描述在幾個段落之內表達出來，那可能這個設計的範圍太大了。將這一章節作為乙個工具，來驗證你的設計範圍是合理的。
第二節 - 定義你的設計中的高層實體：高層實體是組成了你的主要設計結構的物件，或者一組物件。乙個好的實體案例是乙個資料訪問層，乙個控制物件，一組業務物件，等等。圖一顯示了乙個例子：
圖一在這一節中，用幾個句子解釋每個實體會幹什麼。這些描述不必要太繁瑣，只要足夠能描述每一塊的目的就行。確保描述你在圖中定義這一實體的理由，以及它們的角色是什麼。
第三節 - 針對每乙個實體，定義底層的設計：這一節是定義你的物件和物件關係的地方。對每乙個物件(或者物件集)，要定義以下的內容：
在乙個段落中描述物件是如何使用的，它服務於什麼功能。如果乙個物件將會同外部物件或系統互動，那麼展示物件的介面是個好主意。最重要的是，你必須再次描述你定義這一物件的思考過程。列出好處和風險。如果乙個物件提供了封裝，用乙個句子描述為什麼封裝增加了價值。用你的描述賦予圖表內涵。你不需要說得很繁瑣，只需要講清楚就行。
如果你的物件需要特殊的配置或者初始化，這是個好地方去說明。如果沒有，這一節可以省略。
圖二展示了乙個例子，增補圖一中的系統安全實體。這不是完美的uml圖，但包含某些方面的uml元素。最重要的是，它描述了設計思路。
圖二不要擔心你的模型是不完美的，但要確保描述清楚圖表中發生了什麼。此處，兩個具體的安全物件繼承自乙個安全物件基類，乙個安全工廠類會根據系統安全模型建立特定的安全物件。
這一節也很適合畫互動圖。乙個互動圖會展示物件或實體集在完成乙個複雜任務時如何相互交流。圖三顯示了乙個使用者如何登陸的例子。它用到了圖一中的不同實體。
圖三再次強調，此圖不是完美的uml，但它解釋了完成複雜任務時的交流順序。在你想用圖表展示你系統中的乙個物件如何同其它子系統中的物件交流，互動圖是最有用的。這一類圖表可以讓其它開發者核實互動是否正確。
永遠不要移除此章節中的任何內容！如果風險變成非風險，記錄下它們現在不再是風險以及變化原因。不要簡單地擦除它們。同樣的原則也適用於假定。你應該能夠一看本章節就立刻了解當前設計中的風險。
寫給經理的文件
給經理的設計文件的目標，是要保證你的經理能理解系統主要的實體有哪些，有哪些好處，以及最重要的，有哪些風險，文件是你顯示自己理解需求並給出了乙個計畫來實現這些需求的好機會。
如果你寫好了給程式設計師同行的文件，那麼寫給經理的文件是簡單的，因為它僅由1,2和4章節構成。通過用上文描述的方法來劃分文件，通常來說對經理沒有太大意義的部分會包含在乙個章節中，可以直接移除。
結論寫一篇文件最困難的部分跟「寫作」沒什麼關係。難的是你要在開始編碼之前完成乙個符合邏輯的設計。一旦你能洞見物件和實體的組織方式，書寫細節是簡單的。另外，完成這一任務應該不需要除字處理程式和乙個簡單的繪圖軟體外的其它工具。在這一任務上花費一周時間所帶來的積極效應，會在專案結束時帶來難以想象的回報。正如格言所說：「如果你在做計畫上失敗了，那麼你就是在計畫著去失敗」。
怎樣寫作分析文件
網路上很多分析某段 的文件，或是某個資料結構，或是某段演算法。其中有大半自己了解足夠，用來幫助別人卻是大半力不從心。究其原因大多是因為這些文件僅僅說起然，而不談其所以然，只是說了半天這個做了些什麼，至於為什麼要這樣做，這樣做能夠帶來什麼好處卻是未能講的明白，也許有人懂了，但不懂其中奧妙的肯定也大有人...
軟體驗收文件清單 如何編寫有效的文件檢查清單
軟體驗收文件清單 急於發布文件，您還有很多任務作要做。您可能會錯過一些東西。那可能是乙個小東西，或者是乙個大東西。但是為什麼要抓住這個機會呢？發行清單可以幫助您避免犯錯。它可以幫助您提高發布過程的效率。精心設計的清單，無論是在紙上還是在螢幕上，都可以確保文件發布順利進行，並且您不會錯過任何東西。清單...
CSS 書寫有怎樣的功能
隨著公司業務的增加，需求變的越來越多，團隊也因此在不斷的擴大，我們經常會遇到幾個人協同工作來完成同一件作品或者維護修改別人作品的時候，那麼是什麼最讓你最感到困擾呢？我們在實現乙個表現複雜的頁面的同時，css檔案就會比較繁瑣，眾多的選擇符 屬性讓人眼花繚亂，那麼如何更快的定位 如何更高效的編寫樣式呢？...