軟體工程實務：目錄文檔、設計標記、用例建模與設計原則

專案成功仰賴共同語言與流程。本文涵蓋目錄文檔規範、設計標記與流程選擇、用例建模、開放/封閉原則、設計由契約、以及各類實務撇步。

目錄文檔規範 (README)

每個目錄必須包含 README，內容包括：

• 目錄功能與包含內容說明
• 每個檔案的線上說明（含連結），提取檔案標頭屬性名稱
• 安裝、使用說明
• 相關資源導引：原始碼索引、線上文檔、紙本文檔、設計文檔等

目標：新人入職六個月內，僅憑文檔與原始碼標頭，即可獨立穿越整個專案原始碼樹。

採用設計標記與流程

團隊成員技術背景不一，缺乏共同語言會導致無休止爭論、倦怠與進度停滯。送團隊受訓、選定方法論（如 CRC 類別職責卡），統一溝通基礎。CRC 非正式鼓勵團隊合作，聚焦物件行為而非屬性，參考書籍《Using CRC Cards》。

用例建模

用例 描述涉及多個物件的完整交易，或一組物件（如組織）的行為。用例模型蒐集多個用例，規格化整個應用系統行為及外部參與者互動。

• 需求捕獲：用例以易懂形式捕獲系統需求，跑完用例集即可驗證系統行為。
• 流程：理解系統 → 建立用例集 → 建立類別/物件模型 → 跑用例驗證模型 → 更新模型與新增用例。

開放/封閉原則 (OCP)

• Open：類別可擴展。
• Closed：類別除擴展外不可修改。

經代碼審查、單元測試通過的類別不應輕易修改，僅透過擴展新增功能。實務上即善用抽象與多型：抽象萃取共同流程，繼承定義介面約束衍生類別。

設計由契約

契約為程式碼間正式承諾。物件/方法宣稱執行 X，呼叫端信任其履行。Eiffel 等語言以前置/後置條件強制執行，其他語言需靠信任。搭配語言級驗證機制，程式設計如組裝規格零件般可靠。

其他實務撇步

• 離散數值勿用浮點數：浮點數作迴圈計數器如自毀；測試用 <= 或 >=，禁用 ==。
• 拒用自動美化器：美化器僅依語法調整，無法處理空白縮排意圖；養成手工風格習慣。
• 避免邏輯表達式嵌入賦值：if ($abool = $bbool) 易混淆；改為先賦值再測試。
• 用 if (0) 註解大段程式碼：避免 /**/ 不支援巢狀註解問題。
• 存取器風格：Get/Set、單一方法名、屬性即物件三種慣用語，打破直接存取屬性的實作依賴。