l

2012年5月15日 星期二

沒有文件

May 15 09:00~10:29

image

 

鄉民甲因為工作上需要,用了一個前人所寫的元件,但是前人並沒有幫這個元件撰寫使用說明。更糟的是,這個前人早已 到西方取經 離職變成「前同事」,公司內部也沒有什麼人在使用這個元件,導致鄉民甲花了一些時間與苦工才弄懂這個元件的基本使用方法。

還好鄉民甲的團隊有採用Scrum,在retrospective meeting的時候,鄉民甲把這個問題提出來,最後團隊得到一個結論:「為了避免以後有人要使用這個元件的時候沒有文件可以參考,因此下個sprint要安排時間幫這個元件補寫說明文件」。當時Teddy正在案發現場當「烏鴉(觀察員)」,突然有人問Teddy對這個改善方案有何建議。還好Teddy的腦袋最近剛安裝了最新的「三秒開機」功能,趕快從待機模式甦醒過來…XD。

Teddy:請問前人有幫這個元件寫測試案例(自動化單元測試)嗎?

鄉民甲:沒有耶。

Teddy:如果是我的話,我會建議先幫這個元件寫「自動化測試案例」,這樣如果以後還有人要使用這個元件,只要看這些測試案例就知道要如何使用。此外,因為當初開發這個元件的人已經離職了,如果團隊打算繼續使用這個元件,就必須要有「維護或修改」這個元件的心理準備。要維護或修改一個沒有測試案例的元件是很容易出錯的,要是能夠利用這個機會把測試案例給補上去,團隊以後會比較敢放開手去修改這個元件。

鄉民甲:那難道都不用寫「文件」嗎?

Teddy:測試案例也是一種文件啊,更棒的是測試案例這種文件是「可以執行的文件」,可以自動驗證文件與想要解釋的程式碼是否一致(跑一下測試案就知道了,如果測試案例失敗,就知道文件與程式碼已經不同步了。請參考「需求分析書中最重要的資訊是什麼?」提到的觀念)。

***

Teddy並不是反對寫文件,Teddy的思考模式很簡單:

  • Time-Boxing原則:如果你的時間只夠寫文字版的文件或是測試案例,那麼要選哪一種?當然是先寫測試案例啊。
  • 心神不寧原則:如果你覺得不寫某份文件會讓你心神不寧、渾身發癢外加失眠,那麼這份文件就可以寫。
  • 架構優先原則:軟體架構的文件可以寫(方塊圖簡單畫一畫就可以了,不要為了寫架構文件去考什麼UML認證)。
  • 客戶至上原則:給客戶看的使用文件在軟體釋出的時候一定要有(理論上…XD)。
  • 閒閒沒事幹原則:最後,如果你真的太閒了,閒到沒事可做,那麼任何文件都可以寫。

***

多年前Teddy在讀「Working Effectively with Legacy Code」這本書的時候,書中有一個觀點讓Teddy覺得很震撼。一般普羅大眾(包含舊版的Teddy)會認為,「legacy code」就是前人留下來那一堆「看起來好像可以動」,仔細往裡看卻是「亂七八糟外加沒有任何文件(或是有著過時文件)」的程式碼。但是「Working Effectively with Legacy Code」這本書有不同的看法,書上說:

沒有自動化測試案例的程式碼就是legacy code

所以如果平常寫程式沒有寫單元測試,其實每天只是在製造更多的legacy code而已。這些legacy code可能會害到你的同事,或是明天的你(過了一天之後自己都不認得自己寫出來的程式…難道要滴血認親還是用科學一點的方法驗DNA…Orz)。

結論:沒事多寫測試,多寫測試沒事。

***

友藏內心獨白:怎麼扯了老半天這一集又是在談測試。

4 則留言:

  1. 有些古老的元件連Source Code都沒有,就只能Black Box測試,不過只要Unit Test持續寫得夠多,遲早會摸清這個元見的特性,等到你摸清時,就代表已經弄懂元件的內部邏輯,這時候就可以重寫一個了。

    回覆刪除
  2. 不錯的觀點。不過看來沒有 up-to-date , 不可正確執行的 unittest code,也算是 legacy code 的一部份. 一樣會害到別人或自己 XD

    回覆刪除
  3. 如果程式賣給經銷商,而他們要求要看文件呢?給他們看程式碼嗎?

    回覆刪除