現代軟體工程講義 7 設計階段 Spec

在前一個部落格裡 (典型使用者), 我們講了怎麼收集, 分析和驗證使用者的需求。 這裡我們講 spec – specification

Specification, 又叫spec, 有兩種:

    a) functional spec, 軟體功能說明書, 主要用來說明軟體的外部功能, 和使用者的互動情況 (把軟體當作一個黑盒子)

    b) technical spec, 軟體技術說明書, 又叫 design doc, 設計文檔, 主要用來說明軟體內部的設計 (把軟體當作一個透明的箱子)

有同學說, 我們崇尚動手, code & fix 就是我們的座右銘,  寫那麼多文字作甚?  上次來了個需求, 我一看圖紙, 很簡單, 不就是做個煙囪麼?  幹!

做到一半, 使用者來了把我打了一頓!

我冤枉啊

圖紙拿倒了, 原來是要挖一口井!

後來我只好強力 "重構", 把煙囪強力插入地裡去, 累壞了…

笑話講完了，我們繼續講 functional spec: 從使用者的角度描述軟體產品的功能, 輸入，輸出，介面, 功能的邊界問題,  功能的效率問題(對使用者而言), 國際化, 本地化異常情況, 等; 不涉及軟體內部的實現細節

誰來寫spec?  項目的PM, 或者其他人員

誰來實現spec? 開發人員, UX/UI 設計人員

誰來驗證spec? 品質保障人員 (QA)

怎麼寫好spec?  其實就是一件事情描述清楚,  下面是一個練習:

如果你要給一個外星人描述怎麼系鞋帶, 寫一個 “系鞋帶“ 的spec （用英語）, 你怎麼寫?

第一, 我們要定義好相關的概念

—what is “shoe”, “shoe laces”, “tied shoe laces”, and “untied shoe laces”  鞋, 鞋帶, 系鞋帶, 解鞋帶都是什麼概念

—Benefit of this feature “tie your shoe laces”。 系好鞋帶的好處是什麼

—The goal of the feature?                                    系鞋帶的目標是什麼?

—What does “success” look like?                       什麼叫系好了?

—Unambiguous steps to achieve from “untied” to “tied”   明確的步驟來示範系鞋帶的過程

這是兩個同學寫的系鞋帶的spec: 例子1, 例子2。

第二, 規範好一些假設 （assumptions）, 例如, 鞋帶是已經穿好在鞋上的麼? 什麼樣的鞋屬於我們要處理的? 

 

 

第三, 避免一些誤解， 下面這個從技術上也是 ”鞋帶綁緊了“,  但它是 “系好了”麼? 打了死結算成功麼? 要打多少個蝴蝶結才算好?

第四, 釐清一些邊界條件,  下面的情況屬於好的系鞋帶狀態呢,  還是不好的狀態呢？ 這需要PM/Dev/Test 協商達成一致意見。鞋帶要打多緊才算好? 打好的鞋帶能拖在地上麼?

 

 

第五, 描述主流的使用者/軟體互動步驟。

第六, 一些好的功能還有副作用,  我們要把這些副作用明明白白地寫出來。

例如: 美國很多地區用節能燈(LED) 代替了原來的白熾燈,  但是LED 燈泡發熱少,  下雪天不能融化燈面的積雪, 導致交通問題。當初的spec 要把這一副作用 (危險) 給寫出來。

 

 

有人說， 我們敏捷的團隊，就喜歡直接的面對面的交流，不喜歡搞文檔什麼的，多好！

其實大多數情況下，留下文字的文檔是很有好處的，相對於後來的浪費，當初花的時間真的是太值了。 看下面的例子:

自習課時，教務主任走進來，告訴班長“幫我找兩個人，我要班花”,  同時兩手在胸前做了一個抱花的動作,  就走了.  班長就組織全班投票評選起班花來，鬧了一節課，搞了一些大資料, 終於統一了意見，選出了班裡最PL的兩mm。於是兩mm很羞澀的去找主任，主任說：“怎麼是你們? 男生都哪去了?  好吧,  跟我去後勤，我要搬花。。。”

當面, 直接的交流當然很敏捷, 但是還是要留下文檔, 以明確使用者的需求。

 

在大規模軟體的開發中， 我們一定要說清楚服務品質是什麼等級, 意味著什麼，不然就會人云亦云，以謬傳繆。例如: 三峽大壩到底能防多大的洪水?

我們看一看從 2003 年到 2010 年 大家的理解:

人民群眾看不見具體的spec, 只能道聽途說，專家有細緻的解釋:  http://news.163.com/10/0722/01/6C5MUM6R00014AED.html 

寫好的 spec 的秘訣不多, 只有下面三條:

實踐, 實踐, 再實踐

 

spec 的最大敵人是什麼? 乏味。軟體公司的大部分人都不喜歡讀文檔，更不要說大學生了。 強迫大學生寫乏味和沒有人讀的文檔，簡直就是扼殺同學們對軟體工程的興趣。 怎麼把spec 寫讓人讀了不困？

1. 用活生生的人物和故事描述使用者怎樣用軟體的  (參見上文 典型使用者 )
2. KISS - 保持簡單, 直接的描述。涉及UI 的部分可以直接。 也可以畫表格，不要寫長篇累牘的文字。
3. 如果是技術文檔，最好把範例程式碼寫上，單元測試也寫好，讓程式保證spec 的正確性，也讓讀者可以驗證 spec 的正確性。
4. 把邊界條件規定清楚，理工科思維的工程師們看到這裡大腦就興奮起來了 - 他們想找出你 spec 的破綻! 

spec 的另一個敵人是時間。 幾乎在spec 寫好的那一瞬間，spec 就開始過時了。 容顏易老，spec 尤甚，怎麼辦?

1. 記錄版本修訂的時間和負責人 - 這樣出了問題好去找人。
2. 在spec 中要說明如何驗證關於功能的描述，從spec 的描述中就能知道單元測試怎麼寫， 最好把測試案例也連結上。
3. 把spec 和測試案例，專案工作等放一起 (例如 TFS 上面)，相互連結。
4. 變化一定會發生的，與其在 spec 中有意忽略這一點，不如主動挑明哪些部分是容易發生變化的，提前做好預案。 哪些部分如果改變，會有何種連鎖反應。
5. 在做任何改動的時候，一定事先參考spec，事後更新spec,  團隊領導人不應該在沒有spec 的情況下做拍腦袋的決定。

 

有spec  的模板麼? 很多同學問，似乎很多同學有這樣的希望，一旦搞到某文檔的模板， 某課程的PPT，事情就成功了一大半。 盲目地套用最最給力的模板，對項目有大的副作用。 各位PM 要注意。 把上面正反的例子綜合起來，就是一個模板:

1. spec 的目標是什麼，spec 的目標不包括什麼
2. spec 的使用者和典型情境是什麼
3. spec 用到哪些術語，他們的定義是什麼
4. 使用者如何使用軟體的功能的
5. 各種邊界條件是什麼，軟體功能應該怎麼樣變化
1. 這些邊界條件多了去了，使用者數量的變化，輸入內容的上限下限， 不同省/地區/文化/語言/硬體/軟體版本/環境參數….
6. 功能有什麼副作用，對於其它功能有什麼顯性或隱形的依賴關係?
7. 什麼叫“好”,  什麼叫這個功能測試完了，可以交付了?