[雜談] 身為工具開發者的二三事

最近終於有機會可以跟到大專案，而專案中有一人負責提供開發工具。為了方便進行 code review，所有成員要使用該工具。但沒有想到才剛使用一週，就遇上開發者大改架構，而且連個事前通知都沒有，一個禮拜的進度化為烏有。崩潰之餘只好來寫一下自己認知中，身為工具開發者時應該要有的觀念。

提供文件

我知道如果工具還在開發中的話，撰寫文件會比較麻煩，因為只要工具一更新，文件就過時了。但是別忘記，可以多利用註解幫忙生成文件，而且只要符合對應的註解格式，IDE 或編輯器也會為工具的 API 加上提示，讓團隊成員能了解函式或變數的用途。工具完成後也可以用 doxygen 等工具生成 API 文件。

例如 C# 可以使用 xml 格式的註解，配合 /// 或是 /** 來撰寫文件註解，而 Visual Studio 就會為函式加上提示

提供範例

範例是說明工具如何使用最有效的手段。每個範例最好只介紹一個功能，配合常見的使用情況，例如：如何發出事件，就用 UI 的按鈕做為例子、如何生成一個物件，就用生成敵人做為例子。除了能夠讓團隊成員容易理解如何使用這個工具，也可以用來驗證自己的設計是否合理，以及測試功能是否正常。

記錄版本與修改

API 更動時常發生，最好能夠用版本來區分改動，並且記錄 changelog。而不是讓團隊成員在合併分支時，才知道工具又更新了，然後伴隨各種崩慣的錯誤訊息。

使用者可以利用版本號確認自己是否使用最新的工具。我習慣 「Major.Minor.Patch」 的格式，只是修正錯誤就增加 Patch 的數字，增加一些功能就增加 Minor 的數字，如果這次的更新會造成使用舊版工具的程式出錯的話，就增加 Major 的數字。要注意的是，對於 Minor 跟 Patch 的版本變更，都應該要相容前面的版本，即不會因更新而報錯。

版本號的簡單說明

而 changelog 應該忠實記錄每個版本做了哪些修改，讓團隊成員能夠知道如何修正程式以跟上最新版本。我覺得 changelog 至少需要包含增加（Added）、刪去（Removed）、改動（Changed）、修正（Fixed）這幾項記錄。

之前開發的工具所維護的 changelog

開個會吧

如果真的沒有時間可以維護這些文件，那至少集合大家開個會，花個半小時講解一下工具有什麼更新及如何使用。還可以順便收集大家的使用意見，為下一次更新作準備。

結語

如果範例跟文件都有提供的話，我想團隊開發上也會比較流暢，就不用一直詢問什麼功能要怎麼用，耗時又耗神。而且使用者上手後也能夠提供更好的建議。