經驗分享 on Tarragonhttps://tarrragon.github.io/blog/tags/%E7%B6%93%E9%A9%97%E5%88%86%E4%BA%AB/Recent content in 經驗分享 on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Thu, 12 Mar 2026 00:00:00 +0000經驗分享文章的寫作準則https://tarrragon.github.io/blog/record/%E7%B6%93%E9%A9%97%E5%88%86%E4%BA%AB%E6%96%87%E7%AB%A0%E7%9A%84%E5%AF%AB%E4%BD%9C%E6%BA%96%E5%89%87/Thu, 12 Mar 2026 00:00:00 +0000https://tarrragon.github.io/blog/record/%E7%B6%93%E9%A9%97%E5%88%86%E4%BA%AB%E6%96%87%E7%AB%A0%E7%9A%84%E5%AF%AB%E4%BD%9C%E6%BA%96%E5%89%87/<p>整理自 2026-03 測試經驗記錄的多次修改過程。 每一條都是實際犯過的寫作錯誤，附上修改前後的對比。</p>整理自 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 的名稱可以出現在「最終修復」等技術細節區段，因為那是給自己未來查閱用的。

檢查清單

寫完經驗分享文章後，對照這些問題：

  1. 有沒有「你應該」「要記得」「教訓是」這類由上往下的用語？→ 改成描述自己做了什麼、發現了什麼
  2. 有沒有情緒化的措辭（搞砸、偷懶、炸了、根本沒）？→ 改成陳述事實
  3. 程式碼區塊外的函式名稱，不看程式碼的人能理解嗎？→ 用功能描述替代
  4. 每個案例有完整的脈絡嗎？（怎麼發現 → 怎麼找因 → 怎麼修）
  5. 有沒有把不是自己造成的問題寫成自己的錯？→ 用適當的角度描述
  6. 有沒有出現特定產品/SDK 名稱？→ 除了技術細節區段外，用功能描述替代
]]>