經驗分享文章的寫作準則
整理自 2026-03 測試經驗記錄的多次修改過程。 每一條都是實際犯過的寫作錯誤，附上修改前後的對比。
1. 語氣：經驗分享，不是教人
不要用「你應該」「要記得」這種由上往下的口氣。這是在記錄自己的經歷，不是在寫教材。
| 修改前 | 修改後 |
|---|---|
| 教訓：測試應該驅動被測程式碼的真實路徑 | 後來改成從入口方法開始呼叫，Bug 隨即被發現 |
| 教訓：覆寫子類別時，要測試上層呼叫者實際會用到的方法 | 測試覆蓋到的方法，和實際執行路徑走到的方法不是同一個 |
| 關鍵原則：如果你的功能涉及多個元件協作，只寫單元測試是不夠的 | （直接移除，用案例本身說明） |
2. 語氣：陳述事實，不帶情緒
避免用強調語氣、反問、或帶有自責/誇張的措辭。平鋪直敘地描述發生了什麼。
| 修改前 | 修改後 |
|---|---|
| 我到底哪裡搞砸了 | 經驗記錄 |
| 炸了四次 | 陸續發現四個 Bug |
| 說到底，不是測試寫得不夠多，是測試走的路不夠深 | 這次的問題在測試覆蓋的路徑深度 |
| 我寫了一個永遠會過的斷言 | 這個斷言無法區分成功和失敗 |
| 真正會爆的那個完全沒碰 | 測試覆蓋到的方法和實際執行路徑使用的方法不同 |
| 但我偷懶了 | 但模擬的回傳資料只有一行純文字 |
| 其他路根本沒碰 | 其他分支沒有被覆蓋到 |
| 測試全過是假象 | 測試通過不代表修改生效 |
3. 用功能描述，不要用函式名稱
文章的讀者不一定看過這份程式碼。如果只寫函式名稱，只有自己看得懂。函式名稱可以出現在程式碼範例裡，但前後的解說要用功能語言。
| 修改前 | 修改後 |
|---|---|
_buildItemPrinterMapping 沒有被執行 | 品項分派的程式碼沒有被執行 |
applyPrintResult 的資料儲存功能 | 把結果存進去再讀出來，資料有沒有一致 |
只測了覆寫的 sendBytes，沒測繼承的 printText | 只測了「送出資料」，沒測「組裝列印指令」這個步驟 |
generator 未初始化 | 印表機內部元件未初始化 |
_getLexemes('') 對 text[0] 越界 | 解析文字時沒有處理空字串，直接取第一個字元導致越界 |
GeneralPrinterAdapter.printText 加了空字串檢查 | 在呼叫 library 之前加了空字串的前置檢查 |
程式碼區塊裡的函式名稱不需要替換——那是具體的範例，讀者看到程式碼會理解。要替換的是程式碼區塊外的描述文字。
4. 敘事角度：不是每件事都是「犯錯」
有些問題不是自己造成的，不需要用自責的角度來寫。例如第三方 library 的 bug 本來就存在，能觸發它代表前面的工作都做對了。
| 修改前 | 修改後 |
|---|---|
| 修完一個 Bug 我就以為沒事了 | 第三方 library 的地雷——前面都做對了才踩到 |
| 我沒想到修完之後下游還有問題 | 前三個 Bug 都修好之後，執行路徑才真正打通，觸發了這個潛在問題 |
5. 每個案例要有脈絡：發現 → 找因 → 修復
只說「問題是 X，改成 Y」不夠。讀者需要知道完整的脈絡：是怎麼意識到有問題的、怎麼一步步定位原因的、最後怎麼修的。
修改前
測試名稱是「品項分派邏輯」，但分派邏輯沒有被執行。後來改成從入口方法開始呼叫，Bug 隨即被發現。
修改後
怎麼發現的： 實機上兩台廚房印表機只有一台收到品項，另一台完全沒動。但測試裡的分派測試是通過的。
怎麼找到原因的： 回頭看測試程式碼，發現測試裡的分派結果是手動寫死的，不是由分派邏輯算出來的。測試驗證的是「把結果存進去再讀出來」，但品項分派的程式碼從頭到尾沒有被執行過。
怎麼修的： 改成從入口方法開始呼叫，讓品項分派的邏輯實際跑一遍。跑完之後 Bug 就出現了——分派邏輯的 fallback 條件寫錯，所有品項都被送到同一台。
6. 不要用特定產品/SDK 名稱
具體的產品名稱（如某個 SDK 的名字）讓文章變成只適用於特定情境。著重描述問題的結構，而非特定技術。
| 修改前 | 修改後 |
|---|---|
| imin SDK 不驗證 width 總和 | POS 主機不驗證欄位寬度總和 |
| imin vs ESC/POS 有不同的 width 規則 | 兩種印表機對同一個參數的限制不同 |
例外：第三方 library 的名稱可以出現在「最終修復」等技術細節區段，因為那是給自己未來查閱用的。
檢查清單
寫完經驗分享文章後，對照這些問題：
- 有沒有「你應該」「要記得」「教訓是」這類由上往下的用語？→ 改成描述自己做了什麼、發現了什麼
- 有沒有情緒化的措辭（搞砸、偷懶、炸了、根本沒）？→ 改成陳述事實
- 程式碼區塊外的函式名稱，不看程式碼的人能理解嗎？→ 用功能描述替代
- 每個案例有完整的脈絡嗎？（怎麼發現 → 怎麼找因 → 怎麼修）
- 有沒有把不是自己造成的問題寫成自己的錯？→ 用適當的角度描述
- 有沒有出現特定產品/SDK 名稱？→ 除了技術細節區段外，用功能描述替代