撰寫規格文件的重點

一個好的系統除了要有良好的架構之外，他的價值有一大部分是不斷的維護系統而符合需求，貼進客戶的實際需要，這個中間修改的過程除了人的因素之外還有設備的更新，作業平台的轉變所造成的種種變因，所以留下規格文件供未來的人來參考改進非常的重要。

文件撰寫的重點並不是要寫的通順或是像寫小說文章一樣來湊字數，所有的開發文件林林總總，我們這一次討論的重點放在軟體系統規格的部分，由於程式設計師總是覺得寫程式看程式碼就好了，但是如果過了一年之後，你回去看你的程式碼你還會有印象嗎？更何況是別人要看你的程式碼了，其實規格文件的重點只有幾項，就是系統平台、程式碼架構、傳輸協定、檔案(資料庫)架構、模組流程等五大項，有了這些文件，往後的人員只要花個幾分鐘看一下，就可以很容易的維護別人的程式及系統了。

系統平台：其實是最好描述的，只要說明作業系統是Windows95/98或者是Linux、AS/400等等，然後使用的開發工具是VB/ASP或者是Visual C++,BCB 等等，最好要把版本號碼或是一些比較特殊的程式庫也要列上去。

程式碼架構：這一項通常會被大部分的人所遺漏，很多人是靠開發工具所提供的整合環境來分類，固然是很好，但是每個人應用的專案檔案（*.DSW,*.DSP,*.IDE 等等）並不會相同，也就是說你好不容易整理好的專案檔，也寫了一大堆說明文件，但是只是給你自己用而已，這部分最好還是要寫辦法製成文件分享給所有的人。

傳輸協定：無論是區域網路、網際網路的協定，或是單機自己內部傳遞資料一定有傳輸的協定，最普通的當然是TCP/IP了，而現在WEB Server或是EMail Server 的普及很多系統都應用網路七層協定的更高層來傳遞資料，這些都應該說明清楚，如果系統出來問題才知道如何查詢，而Windows系統內的訊息傳輸，也算是傳輸協定的一種，而兩個模組之間的Function傳遞也是，如果是重要且獨立的元件模組，應該要特別的強調才是。

檔案(資料庫)架構：除了關聯式資料庫比較容易寫出規格之外我們經常應用到的設定檔(Config)，例如*.INI的檔案，還有為了系統效能或是儲存資料、交換資料所儲存的資料檔案，應該都要有格式的說明，以及生成時間版本號碼的資訊，有了這一個規格表，即時是程式碼不見了，我們都可以很容易的重寫出部分的模組，而不用經常得去猜去破解一些資料檔的格式。

模組流程：是最早最早結構化資料分析的時候必須具備的流程圖，但是在物件導向的程式開發，我們經常會把流程圖隨著物件化而簡化，但是也僅僅是改良罷了，他的精神就是輸入與輸出的前後順序一定要清楚的表達出來，雖然現在的程式系統應用了很多訊息是觸發的事件來處理或是多執行緒的程式處理，一個良好的流程圖也可以表現出一個系統的邏輯性，有助於找出系統需要改進的地方，與如何維護的方向。

做文件並不是主管或者是某一些人的責任，應該是所有的程式設計師應該培養要定期製作的能力，除了可以有良好的溝通方法之外，也可以重新檢視一下自己的系統架構，把自己的能力向上提昇。

Reference:
http://next.writers.idv.tw/2001/01/blog-post.html