沒有文件

May 15 09:00~10:29

 

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

還好鄉民甲的團隊有採用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）。

結論：沒事多寫測試，多寫測試沒事。

***

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