G26 建立第一版的同時建構維護基準

終於，忙碌許久的系統終於要出第一個正式版本了。收集的需求、功能規格書、Data Model、系統硬體架構、設計規格書、元件規格書、實作的程式、測試程式、測試報告、API參考文件、系統安裝手冊、系統使用文件、系統開發教學文件……等等所有與系統有關的物品，全部都要在剛出完版本的那一刻進入建構管理。

為什麼要建構管理？首先當然是讓日後使用的人明白與現在版本相關的一切都在這個建構之中，取出的任何物品都是正確的版本。以前公司的專案曾經發生過負責人員沒有把專案最後版本的程式碼放回公司伺服器，使得後來去維護的人在找不到從哪個版本去改的狀況下，從程式反推需求後再寫出對應的程式。原先十分鐘可以改好的問題後來花了整整兩天在處理。當然，那個歹命的人又是我。

千萬要記得，系統每出一個版本，與當時系統有關的所有程式與文件也要建立一個對應的建構的版本，這是最基本的觀念。但是不要以為依版本收集妥當就沒事，同時還必須要建立現在版本與上一個版本之間的全部差異！

G25 追溯關係(5)──System vs Document

一直認為每一個動作都會有它必須要做的來由，動作會有它的產出，也會有它的影響。基於系統的功能目的，會有對應要有的程式，接著有對應來保證程式運作正常的測試程式，有對應程式開發的API參考文件，也有教使用者使用的說明文件。

文件與系統的對應追溯差不多就是如此。系統上的每一個物件都有它所對應的功能規格，也有它所對應的使用文件，不管是程式、元件、設定檔或是訊息檔，裡面的每一個小項目都有其應該對應的來龍去脈。

很明白地，需求、設計、程式、測試、文件、使用是一脈相承的連續產出，有前面的需求才會有後面一系統物件的存在；唯有記錄其中的關係方能明確地知道動了其中一個部分的時候，同時會有哪些東西需要跟著修改。只要忘了或懶得建立其中一項關聯，那麼在需要知道追溯關係的時候就難以再分析求得。

G24 英文字典vs英文課程──API Reference vs Tutorial

當我們開發好系統後，要如何讓其他原先不懂的人明白如何使用系統內部的程式來做出想要達成的動作呢？最理想的方式莫過於使用Tutorial循序漸進地來引領大家慢慢瞭解系統的內部。

公司的產品剛做出來時，提供給相關的專案作客製化時，專案人員抱怨說新的產品不知道要怎麼用，不清楚有哪些API。的確，產品剛出第一個版本時的說明文件少得可憐，做出來的說明文件坦白說實在有點不知所云，連我看了都不懂裡面的狀況，更何況資歷更淺的人呢？

有人提議說把教學文件做好一點就夠，但是我堅持應該要有系統所有的API參考文件。Tutorial就像是課本，會說明其他人所希望知道的系統，可是教學不可能教全部的東西，應該另外有一份所有東西的參考資料存在；就像英文字典會收集世界上所有的英文單字，而我們的英文課本只會選擇出英文字典裡最基本，最需要學會的一些單字來教學。

API Reference與功能清單很類似，後者是列出系統全部可以做到的事，前者則是列出系統內部可以使用的Class與方法；相同的是兩者都需要記錄才有可能寫出內容，這是直接把想法寫成程式的作法難以做到的。

G23 驗收的文件(11)──系統開發教學

一般只提供使用的系統，交付安裝手冊與使用手冊後就可以過關。但是系統如果要交給客戶自己維護，甚至自行在系統上開發新功能時，那就得再交付一堆下述的文件才能過關。

首先要有開發環境的安裝手冊，包括開發伺服器的安裝、開發工作站的安裝，同時應該會需要安裝同步開發時控管的軟體。接下來要開發使用的工具軟體清單、安裝手冊與使用手冊，再來是如何建立原始程式工作區，如何使用同步控管軟體；以及前面提到的系統API參考手冊。

前面這一堆都還只是準備動作的文件而已，開發的重頭戲在於要怎麼教會使用者系統的精神、架構的意義，接著是一步一步地帶領使用者由淺入深地慢慢懂得如何使用API來組合成他們想要做的動作。之前為我維護的系統撰寫這一部分時，光是最上層開發或維護Use Case花了五天才寫出細節不夠完整的教學文件，講授時則是用了三天才講完較基礎的部分。

每一件想做的事物都必須投下相對的人力與時間，在此又是一個有力的印證。

G22 驗收的文件(10)──系統使用手冊

將所有的電腦都安裝妥當後，接下來要教客戶怎麼使用系統的功能。設定、起動與結束是最基礎的幾個功能。

使用手冊大致上依照Use Case包含的Activity Diagram裡的User那塊swim lane的動作依序講解下來，在需要操作系統的時候貼上一張圖顯示要在哪裡輸入些什麼，系統有回應時解釋各種不同的反應代表什麼意義，接下來要怎麼做等等。原則上依每個Activity以一個步驟來講解為宜。

如果系統有明顯的子系統區分時，要編排不同的使用手冊。例如系統含有使用者管理與管理者監看系統狀態等等的功能時，由於使用者角色的不同，這些都應分開為每一種角色的使用者撰寫一份使用手冊。可以考慮由測試人員在Test Case測試時，把結果正確的測試步驟一一轉出為使用文件的內容並擷取對應的系統畫面。

每一份使用手冊也需要針對其範圍另外編寫系統的可執行功能清單、可用參數列表、錯誤訊息清單、詞彙表等等的章節作為參考。這部分應可在設計文件中得到並附加在使用手冊後面。

G21 驗收的文件(9)──系統安裝手冊

根據硬體架構與設計文件可以知道系統有哪幾類的電腦，每一類電腦的硬體規格、應該接續哪些週邊、使用什麼作業系統、安裝哪些軟體、需要哪些程式執行檔等等。系統安裝手冊就是循序漸進地帶領使用者建置起各個角色的電腦設備。

安裝手冊的編排要按照先後次序，內容則要巨細靡遺地說明每一個步驟，附上執行該步驟時的畫面圖檔或是擷取安裝時的動作影片都是讓使用者更能明白安裝操作的理想方式。製作安裝手冊的人通常會拿一台符合規定的乾淨電腦，按照規定從無到有地依序安裝並且設定，同時將所有過程按部就班地記錄成安裝手冊。安裝手冊裡每完成一項軟硬體的安裝與設定後，應該說明如何驗證該項軟硬體已經正常安裝的動作以便確認。

如果系統需要交給客戶使用開發環境，那麼安裝開發環境也需要另外製作出一份安裝文件。總之，每一種用途的電腦都該有一份專用的安裝文件。

G20 驗收的文件(8)──系統測試報告

關於系統的每一種測試的時間與結果報告，都應該彙總起來在驗時交付的。

系統程式碼的Unit Test會與原始程式一起交付，在開發環境裡隨時可以執行驗證正確性。這方面的報告只要填寫何時跑過全部的Unit Test且沒有任何錯誤即可。

與Use Case有關的Test Case應被追溯，測試時開立的問題單都會註明屬於哪一個Use Case，修正後再用該Use Case的所有Test Case重測一次。

對於系統來說，每隔一段時間就應跑出一份報表，記錄各個Use Case至今總共測出了幾個問題、修正了幾個、修正的百分比多少，這些數字也會被加總在子系統層級與整個系統層級來表現。測試階段時每隔一段時間就要跑出一份這樣的測試報告，所有的報告都應交付並建檔管理。

G19 驗收的文件(7)──ＡＰＩ參考文件

在OOAD開發流程下，在每個Class、每個方法與每個屬性被設計出來的時候，應該都已經有它應該存在的原因與其對應要去處理的動作。在Java的開發環境裡，幾乎只要使用Java Doc把所有程式碼的註解跑過一遍就可以擁有完整的API文件了。

在Component的情形下，除了基本的註解顯示的內容，應再附上Properties使用的名稱與其影響的功能，以及在各種不同的例外狀況下傳回Exception裡的所有傳回狀況代號；如果有使用到任何外部檔案的時候，也要包含檔案格式的說明。當然這些在元件設計的時候都應該同時有追溯表才是。

在把方法視為函數呼叫的類別裡，最重要的是詳細說明每一個方法的呼叫方法與作用，最好是能附上幾個使用範例。這些內容的寫法可以參考JDK的API文件寫法。

對開發與維護的人員來說，API參考文件就有如系統的開發API字典一樣，要包含系統層次裡所有可能會使用到的Class、方法與屬性說明。

G18 從程式倒回Design Model的問題

身邊偏好將想法直接變為程式的人常說，程式裡隱含可正常執行的Model，如果需要UML圖的話就從程式碼倒回來，保證可以拿到最新最正確的。

這句話原則上沒有錯，無論是Class Diagram或Sequence Diagram都是系統真正在執行的。但是令人困擾的是倒回來的Model是一大包什麼都有的產出，我們不容易從裡面找到我們所需要的條理，也不容易正確地分辨系統的層次。更要命的是，要是設計者只是為了功能而實作，倒回來的東西可像極了混成一大團的毛線球。

試過用IBM RSA把維護系統的程式碼倒回Sequence Diagram，得到的結果實在很長，一個特定方法之下所有呼叫順序全部都列出來。由於該方法原先就沒寫好，有些邏輯在上層，有些則放置在更下面的邏輯裡，完成不知道原先設計者思考的是什麼；後來只好去問原來的設計者，得到的答案竟然是：我忘了，你可以先看程式碼後再問看不懂的地方嗎？當然我就丟下不看了。

設計的層次本來就有問題時，怎麼倒回Design Model都是沒有用的，頂多貼到交付文件裡騙騙那些什麼都不懂的使用者。建議還是先用Model設計，確保各個層次與物件負責範圍，以免系統最後變成一團大毛線球。

G17 程式設計的能力(5)──取得狀況、判斷資訊與執行動作

做事與寫程式的理念實在太接近了，因為二者的在細節上的處理同樣都是取得狀況、判斷資訊與執行動作。

做事情是為了達到目的，但並不是一味地往前直衝而已，而是需要判斷現在的局勢然後決定一個最適合的作法，執行作法後還要再檢查結果與影響並進行再下一步的動作。程式設計也是如此，我們可能設計直接執行一個動作，或者先取得系統裡某些地方的資訊，加以判斷狀況後執行不同的動作，當然也會根據執行後的結果來取決接下來要做些什麼。

開發系統的時候，在商業邏輯的處理時主要著重於配置物件、定義動作與要處理的資料這類的思維；再詳細設計商業動作內部的分解行為時，則是以取得狀況、判斷資訊與執行動作這樣的想法來逐步堆疊出達成方法目的的內容。

G16 驗收的文件(6)──系統原始程式

這部份應該比較沒有問題，再怎麼樣都只要把專案裡用到的所有程式碼，一股腦地壓成光碟直接丟給客戶存查就鐵定沒錯。不過在一般的專案裡由於沒有控管與追溯，裡頭大多都帶著一堆雜七雜八沒用的程式，也沒有人敢任意拿掉什麼，因為就怕拿了一個Class後讓系統再也跑不起來。

以架構與元件設計的產出為基礎，分門別類地把Package放到所屬的資料夾。在每一個Package與每一個Class的產生都能找出原因，且能找出誰在使用時，在專案裡要出現多餘無用的程式是很不容易的；只是要有這樣的效果，都是必須投入時間從頭開始分析、設計並記錄才能享有的。

測試用的程式最好也在原始程式的交付範圍，因為要驗證原始程式執行時的正確與否，使用曾經使用的測試程式是最快的；同時也可以檢查測試程式裡寫入的測試範圍有哪些，而且可隨時加上新的測試內容來驗證原始程式。

G15 程式設計的能力(4)──配置物件、定義動作與輸出入資料

當我們可以正確地拆解動作與物件，同時也瞭解異中求同、同中求異的概念後，接下來要做的就是把拆解下來的各種不同的“零件”依概念組合成系統需要的Design Model。這時候還需要參考的設計理論是Design Principle與Design Pattern。

物件的放置與群組化的處理可以根據Design Principle，像是OCP（開閉原則）、DRY（勿自我重複原則）、SRP（單一責任原則）、和LSP（Liskov替代原則）等OO設計原則，期望產生可擴展、可重覆使用、且好維護的系統。在需要達到特定的需求且避免可能的問題時，則套用Design Pattern的設計來塑造具有彈性的局部設計。

接下來就按照物件分析出來的關係，根據動作的先後一一在對應的物件上加上適當的方法；在此同時將傳入的參數、傳回的結果與拋出的例外一併宣告。如果設計的是元件，則建議將可能會有多形使用的方法一併加上，以減少未來變動時再度產生改變的影響。

系統再怎麼做幾乎都能滿足客戶的需求，但是系統要能有彈性、易變動、好維護之類的特性，就全仰賴設計者有多少能力了。

G14 元件切割大小的抉擇

元件在定義時就需要花上功夫。由上而下設計時，開出的方法包含的範圍是比較大的，屬於Controller裡的一個特定動作；但實作時我們會發現許多真正要實行的動作是更加細微的；這之間的落差該怎麼辦？

我們當然可以只用一個方法來含括符合Controller動作裡想要做的事，這樣一來在Controller上簡單易懂；只是在Component實作時會在裡面處理較多的邏輯與動作。元件寫得越大，內部邏輯包含得越多，也越加讓這個元件只能符合部分的需求。

為了讓元件符合重用並滿足更多樣化的需求，我們也可以讓元件控制的範圍最小化，如此一來就有機會任意組裝順序以滿足不同種類的動作需求。但是元件寫得越小，就得加寫上層的控制動作，使得Controller的管理變得煩瑣。

我的解決方案是使用複合型的元件。需要直接使用底層控制元件時，就用最小單位的Component；在較多邏輯的情況時，就在原先的元件外再多包裝一個大的元件，讓原來的元件只是大元件內部的Action，邏輯就集中在大元件的Component Controller來做。如此一來就能依想使用的範圍選擇適合的元件。

G13 驗收的文件(5)──細部設計相關文件

如果執行的步驟是經過設計一段程式碼，那麼通常會獨立成一個方法。這時需要方法的宣告規格，然後是裡面所做的流程與各個步驟執行了些什麼。

如果執行的步驟經過設計是獨立一個元件來負責處理，那麼我們會先定義出Component Interface的規格，再依照Component Interface的定義在一個（或數個）Package裡設計出一些Class來完成Component的應有規格。

以細部設計裡所提到的想法，靜態部分會有實作Class與Component Controller、Component Action兩層，另外還有Properties的定義以及Component Exception；動態部分則應該要有每一個介面方法在執行時的順序。依此可以得到Component的Class Diagram與Sequence Diagram。

別忘了架構設計時使用的元件方法追溯是維護時很重要的一份文件。

G12 程式設計的能力(3)──異中求同，同中求異

在多個不同的地方找出共同的部份抽取出來，在抽取出來的共同部分裡又能分辨出差異的地方。聽起來有些玄妙，但是這卻是要做好設計不可或缺的能力。

從物件角度，系統每個物件都是各自獨立的物體，我們必須去分析物件間的共同關係，將之抽取為Interface，在處理Interface時又必須可以分辨出它的實體是哪一種物件。

從程式角度，某一段程式碼在多個地方出現，因此我們會將之獨立成一個子方法供需要的時候呼叫，但是在子方法裡要能知道是從哪裡呼叫來的。

從系統角度，每個Use Case都被設計為一個View對應一個Controller彼此是沒有交集的，此時會在所有的View進入Controller之前加上一個Façade作為共同經過的處理，在Façade裡必須知道現在進入的是哪一個Use Case。

共同的部分是要作為reuse使用的，差異的部分則是用來區分每個物件、程式或Use Case的唯一性。找出同理與區分差異的動作做多了，現在幾乎隨時隨地都在對身邊的所有對話與事件作推理，這應該屬於職業病的一種吧？

G11 做人的方法(6)──明白自己的定位

在系統裡處理事情的單位有Controller與Action，對應到現實生活上同樣也有管理者與執行者的角色。管理者負責決定事情應該有哪些動作並控制現在執行的狀況，執行者則負責執行特定的動作並向管理者回報執行的結果與無法處理的狀況。

人在參與事情時應明白自己的角色：管理者決定好動作並分派給適當的執行者去做，隨時蒐集各個執行者的狀況並參考調整接下來的動作與時間點；執行者只需要努力在限制時間內做好指派的工作，在有結果或是應由管理者決定的例殊狀況時立即向管理者回報。管理者若管得太細會有失焦的可能，執行者若把管理者該作的決策自己決定掉了則會有失控的狀況。

開車在路上時，對於車子而言我們是管理者，但是對於後面的車來說我們卻是執行者。開車時，我們要不斷地接收路況、車況等等的資訊來決定要如何駕馭車輛；另一方面我們又必須使用燈號讓其他車輛明白我們接下來會不會有加減速、轉彎等動作，好讓其他開車的人控制他們的車作好配合的準備。應該可以想像車禍的發生大多是駕駛無法控制好自己的車，或者其他車子沒有告知接下來的轉變而來不及反應。

人應該明白自己當下所處的位置與應該做到的責任，才比較不會搞砸事情。

G10 驗收的文件(4)──架構設計相關文件

在架構設計的那些文章裡，根據MVC的原則畫分了系統的各個層次。架構的層次可以依照實際的狀況調整，比如像上一節的Web-Presentation-Business-Integration-Resource就被分為五個層次。

每個層次如果應用了一些Design Pattern或者是打算設計為Framework，那麼為了形成系統的架構，就必須先有形成系統框架的程式；這當中也包含了各個層次或硬體之間資料傳遞所必須的橋樑設計。如果有這樣的設計，在這部分就應該先有框架的功能規格，裡頭應包含Class Diagram、Component Diagram與Sequence Diagram。

每個Use Case依功能規格書，以符合框架設計為前提被設計成一堆Class，Class裡依步驟的解析會有使用到Component的動作。在Use Case Realization裡記錄的時候向下只需記錄到使用Component Interface的哪個方法即可，主要記錄的內容著重在陳述Use Case裡的各個步驟與遇到的各個狀況要如何處理。這部分的文件應包含Class Diagram、Sequence Diagram及其他視需要而畫的UML Diagram。

請記得這時雖然還沒有牽涉到Component的內部，但需要記錄使用哪些Component以及使用了什麼方法。

G09 驗收的文件(3)──硬體架構相關文件

系統的程式要佈署到Client與Server上時，有些人的作法是在每一部執行的電腦上放置一份所有的程式，那麼不管在哪一部電腦“肯定”都可以正常執行。

當然以使用者的角度來看只要系統正常運作，其他都是次要的問題，可是一部電腦裡明明放了一大堆根本用不到的東西，卻又無法明確指出哪些是必要的，哪些根本用不著會不會太浪費資源了些？如果放置物品的地方是你的房間、你的車或你的床，你會容許把一大堆有的沒的全堆在裡頭嗎？

隨時隨地建立關聯的追溯是可以立即追蹤出指定的物件是否必要的最快方式。從Usc Case、Library、Framework、Component、Class一路追溯而下，所有物件應該在什麼地方出現並被使用都可以知道它為什麼要存在。

下圖來自Sun OO-226課本第15章的Tier and Layer Diagram，是個不錯的範本。硬體架構的決定將會影響再上一層的架構設計，並會由此導出安裝手冊的內容。

G08 程式設計的能力(2)──能夠拆解物件

程式設計的另一個能力是物件組織能力。能夠準確無誤地從一堆雜亂的名詞挑出適合作為Class與應該是其對應屬性，並分析出所有Class之間的參照關係，是建立Data Model的重要基礎。這個能力其實不難培養，通常有兩個方向可以思考。

一種是觀察靜態物件的組成。生活裡有很多實際的物品，每件獨立的物品我們都可以仔細觀察它擁有了什麼特性：像是顏色、尺寸、形狀等靜態描述，或者是動力、移動方式、跳躍等動態描述，這些都屬於物品的特性。還有物品是否使用了其他的子物品？像是汽車裝的輪胎就可以視為子物品而存在，這樣擁有的關係也需要記錄在物件裡頭。

另一種是動態關係的組成。在拆解目的時我們會得到許多工作步驟，精確地把每一個工作步驟指派到應該執行它的靜態物件，就是最終的目標。要往這個方向邁進，我們必須清楚的知道每個靜態物件的責任，才能判斷出該由誰來負責。這同樣是日常生活與工作上時常會遇到的情境。

我們並不能保證每個人想的分類都會是正確的，因此需要review的機制來驗證每個人的想法並加以調整。

G07 驗收的文件(2)──Data Model相關文件

系統所要處理的是資料，資料在系統裡面不會漫無目的地到處亂放以免增加存取的難度，因此我們會將輸入輸出用的資料，依用途與關聯分門別類地建立盛裝的Data Model。

Data Model裡的Class名稱與內部的屬性應該都可以在系統詞彙表裡面找到並定義其關聯。Data Model是很重要的設計，由於這是最底層被使用的模組，所以必須要求物件之間的關係，不管是擁有或是使用關係，都必須是正確的。一旦後來發現錯誤調整了關係，那麼會連帶地影響所有使用到變更部分的程式內容，影響是十分龐大的。

Data Model文件主要要表達的是一共有哪些資料物件，內部包含了哪些屬性，以及與其他資料物件之間的從屬及使用關係。可以選擇用Class Diagram表達，也可以選用ER Model來表達這些內容。資料實際儲存的格式也要同時記錄下來，不管是XML的格式或是資料庫的語法。