當 filter 必然只在已載入子集上運作、用 UI 文字 / API contract / docstring 明確告訴呼叫者「範圍 = 已載入、不承諾全集」 — 不假裝是全集 filter。

對應 #59 Filter × Source 合成策略 的策略 E。

何時用、何時不用

用

• Source 不支援推進 query (A 不可行)
• 不能控 build pipeline (C 不可行)
• Match 稀疏、自動續抓會拉爆 (B 不可行)
• 工程量限制、做不了 #62 誠實 UX 的三數字
• 能接受「filter 範圍 = subset」這個語意縮小、但要使用者知道

不用

• Source 一次給完整 dataset（沒有 subset、不需要縮小）
• 使用者預期 filter 是「全集」、無法接受縮小
• 應用情境影響重大決策（finance、medical 等不能接受 silent 範圍縮小）

跟策略 D（誠實 UX）的差別

D 跟 E 都是「在 subset 上 filter」、差別在「怎麼告訴使用者」：

簡言之：D 是「持續顯示掃描範圍」、E 是「告訴一次、之後不再提」。

「明示」的具體做法

UI 明示

1<input type="search" placeholder="Filter loaded results...">
2<small class="hint">只在已載入的結果裡篩選。要看更多請先載入更多。</small>

「Filter loaded results」、「已載入的結果裡」、「載入更多」 — 三個 cue 讓使用者知道範圍。

API contract 明示

1/**
2 * Filter loaded results by predicate.
3 *
4 * NOTE: Operates on currently loaded subset only.
5 * Does NOT trigger fetch of un-loaded items. To filter the full
6 * dataset, use {@link searchAll} instead.
7 */
8function filterLoaded(predicate: (item: Item) => boolean): Item[];

JSDoc / TSDoc 把語意寫進 API、IDE 提示能看到。

Docstring / README 明示

1## Filter behavior
2
3`filter()` only operates on results currently loaded in client.
4If the source uses pagination, items not yet loaded are NOT included.
5For full-dataset filtering, the source must support server-side filter.

文件級的明示、給開發者讀。

反例

反例 1：Silent 縮小（不告訴）

1<input type="search" placeholder="Filter results...">

「Filter results」沒指明「only loaded」 — 使用者預設是全集 filter、實際是 subset → 撞回 #55 層錯位 的語意縫。

反例 2：明示位置使用者看不到

1/**
2 * Filter results.
3 * Note: subset only.
4 */

使用者只看 UI、不讀 docstring — 「明示」要在使用者會看到的位置（UI hint、tooltip、行為描述）。

反例 3：明示但不清楚

1<small>限定範圍篩選</small>

「限定範圍」太抽象、沒說明是什麼範圍。要寫具體：「已載入的 N 筆內」「不包含尚未載入的」。

何時 E 升級到 D

當以下任一觸發、把 E 升級到 D（誠實 UX 三數字）：

E 是「成本低的退路」、不是長期解。當需求成熟、應該升級到 D / A / C。

跟其他 Pattern 的關係

• E 是策略順序 A → C → B → D 之外的「最後退路」
• E 跟 D 都是「在 subset 上做」、差別在告知方式
• E 跟 #55 silent 反模式的差別：E 是 explicit 縮小、silent 是 implicit 縮小

選擇順序（重申）：A 推進 → C 多 index → B 自動續抓 → D 誠實 UX → E 明示縮小 → silent（反模式）

判讀徵兆

核心原則：能接受語意縮小是可以、但必須明示。Silent 縮小（沒告知就 subset）等於 #55 層錯位、是反模式。E 的價值在「明示」這個動作、不在「subset」這個事實。

核心命題：source code doc 寫給「未來的讀者」，commit message 寫給「想了解過去發生什麼的考古者」。兩者是不同文件，內容該分開。 設計原則：時序敏感的資訊（為什麼這次改動、考慮過什麼方案）放 commit；持續適用的資訊（當前契約、不變量）放 source。

本篇是 函式文件分層設計 反模式 3「過去式 doc」的展開——把「source 跟 commit message 的時序職責邊界」拉成獨立主題討論。

起點：兩份文件的職責容易被混在一起

Source code doc 的職責是「描述當前 code 的契約跟行為」、commit message 的職責是「描述某次改動做了什麼跟為什麼做」——兩者讀者不同、時序屬性不同、本該各歸各家。實務上這兩份文件的職責經常被混在 source code doc 一處：source 變成所有歷史的垃圾桶、commit message 反而沒人認真寫。

實務上常看到的污染：

1/// 修了 issue #123 的 race condition
2/// 從 v2.3 開始改用 lock-free 結構
3/// TODO: @alice 之後可能要改用 SkipList
4void process() { ... }

這段 doc 混了三類資訊：

1. 過去發生什麼（修了 issue #123）→ 屬於 commit message
2. 過去做過什麼決定（v2.3 開始改用 lock-free）→ 屬於 commit message / changelog
3. 未來可能要改什麼（TODO @alice 改用 SkipList）→ 屬於 issue tracker / TODO 系統

沒有一條是「未來讀者讀這份 code 需要的資訊」——三條都凍結在過去某一刻、source 卻被當成歷史快照在用。要釐清這個問題、得先想清楚兩種文件各自的讀者與時間性。

時序差異：當前狀態 vs 狀態轉移

關鍵差別是時間性：

• Source code doc 描述「現在這份 code 在做什麼」——只要 code 不變，doc 就持續有效
• Commit message 描述「那一刻為什麼要改 code」——commit 完成的那一秒就成為歷史

把過去式的內容塞進 source code doc，會讓 doc 變成「凍結在某個歷史時點的快照」，而不是描述當前狀態。

該寫在 commit message 的內容

Commit message 的核心職責是回答「這次改動做了什麼、為什麼做」——所有「凍結在某次提交時點」的資訊都應該住在這裡、而不是被塞進 source 變成過時快照。下面四類是最常被誤放進 source 的內容：

1. 改動的動機（為什麼這次要動）

1fix: prevent double-charge on payment retry
2
3Payment gateway 對同一個 transaction_id 會回傳 200 但實際扣款兩次
4（incident #4521）。在 client 端加上 idempotency_key，gateway
5看到重複的 key 直接回 cached response。

「為什麼動」幾乎永遠屬於 commit message。source code 只需要描述「現在的行為是什麼」，不需要解釋「過去為什麼變成這樣」——除非那個「為什麼」對未來呼叫者仍是必須知道的限制（見後面段落）。

2. 評估過的替代方案（why not X）

1refactor: replace stream with reactive value
2
3考慮過三個方案：
4- A. 改成 broadcast stream：最 minimal，但保留同樣的 payload 語義模糊問題
5- B. 加新 broadcast stream 平行存在：兩條 stream 容易不同步
6- C. 拆成 reactive value（採用）：與系統其他 service 一致、消除多訂閱問題
7
8選 C 因為與 codebase 其他 service 風格對齊，雖然改動範圍最大。

「考慮過 A、B、C，選了 C」這類資訊對 reviewer 重要，對未來讀 code 的人多半不重要——他們看到的是 C 的結果，不關心你考慮過 A、B。這類資訊屬於 commit message / PR description，不屬於 source code doc。

3. Migration / 部署相關步驟

1feat: migrate user_profile from int_id to uuid
2
3注意：
4- 跑 migration 0042 之前先確認所有 client 已升到 v3.2 以上
5- migration 預估 2 小時（10M rows），建議週末執行
6- rollback：reverse migration 0042 然後 redeploy v3.1

部署時序與步驟是當下發布動作的一部分，commit / release notes 該寫；source code 不該背這個負擔。

4. Bug 號、ticket 連結、incident 紀錄

1fix: handle empty cart in checkout button visibility
2
3Closes #1234
4Related: incident-2026-04-12 (button stuck enabled)

把 ticket 號 / issue 連結寫在 commit message，git blame 出來的 commit 直接帶你去原始討論。寫在 source code 反而會 outdated（issue 關了、tracker 換了、URL 改了）。

該寫在 source code doc 的內容

Source code doc 的核心職責是描述「當前 code 的契約跟行為」——只要 code 不變、doc 就持續有效。下面四類是「持續適用」的資訊類別、屬於 source 的家：

1. 當前對外契約

1/// 從本地購物車移除指定商品
2///
3/// 找不到對應品項時不做事；不會拋例外。
4void removeFromLocalCart(CartItem item);

這是「現在這個 function 對 caller 承諾什麼」——持續適用，跟「上週為什麼加這個 function」無關。

2. 隱性需求 / 必要的呼叫順序

1/// 必須在 [init] 之後呼叫；否則 throw `StateError`。
2void process() { ... }

「呼叫順序」是當前 code 的契約限制，未來呼叫者必須遵守。屬於 source code doc。

3. 對未來讀者仍然重要的「過去原因」

少數情況下，「為什麼以前這樣決定」對未來讀者仍是必要資訊——典型是「這個寫法看起來怪，但有非顯然的原因」：

1void processPayment(Payment p) {
2  // 刻意不 retry —— payment gateway 是非冪等，retry 會造成重複扣款
3  // （見 incident-2026-04-12）。失敗一律拋給上層人工處理。
4  return _gateway.charge(p);
5}

這條註解兼具「歷史原因」和「持續適用的限制」——未來維護者看到這段 code 會想「為什麼沒 retry？」，這條註解防止他「順手加上」。這類兼具兩種性質的內容是少數該留在 source 的歷史相關 doc。

判斷標準：「未來讀者不知道這條歷史會做錯決定嗎？」

• 是 → 留 source
• 不是 → 留 commit

4. 不變量 / invariant

1class CircularBuffer {
2  /// 元素數量永遠在 [0, capacity] 之間
3  int get length => ...;
4}

不變量是「這個型別永遠成立的事實」，是契約的一部分，屬於 source。

反模式

反模式 1：把 commit message 內容塞進 source

正向概念：source code doc 描述「現在的行為」、git log 才是「歷史演進」的家。兩者各自有對應的工具（IDE 看 doc、git log 看演進）、各司其職就能讓兩邊都精準。

 1// 反：寫成歷史紀錄
 2/// 2024-01-15 加上 retry 邏輯
 3/// 2024-03-22 改用 exponential backoff
 4/// 2024-07-08 加上 jitter 避免 thundering herd
 5Future<Response> fetch(String url) { ... }
 6
 7// 正：source 只寫當前行為
 8/// 自動 retry 失敗的請求，使用 exponential backoff + jitter
 9Future<Response> fetch(String url) { ... }
10// 演進歷史在 git log 看

把所有歷史塞進 source 等於在 source code 重做一份 git log——但 git log 已經存在、且結構化、可搜尋、有 author / timestamp。重做一份在 source 只會 outdated（下次再加邏輯時忘了補日期就破功）、而 git log 永遠是同步的。

反模式 2：commit message 只寫 “update” / “fix”

正向概念：commit message 是給未來考古者的線索——git blame 跳到一個 commit 時、message 是讀者拿到的第一份資訊。寫得清楚、考古路徑就短；寫得模糊、考古者得繼續挖 PR / 找原作者問。

1- update
2- fix
3- wip
4- final
5- final v2
6- final v2 真的

這類 commit message 當下就沒人看得懂、半年後 git blame 把人帶到 message 寫 “update” 的 commit、等於把讀者帶到死巷。合理 commit message 的最小單位是 <type>: <one-line summary>、例如 fix: handle empty cart in checkout——一行就好、但要說清楚做了什麼。

反模式 3：source code doc 寫滿 TODO / FIXME

正向概念：「想未來改但還沒改」屬於 issue tracker——issue tracker 有優先序、有 owner、有 due date、能被排程。source code 的 TODO 沒有這些屬性、會被慢慢遺忘。

1/// TODO: refactor to use streams
2/// FIXME: handle null case
3/// HACK: temporary workaround for issue #234
4/// XXX: this is broken under high load
5void doSomething() { ... }

這些都是「想未來改但還沒改」的事——把它們留在 source 有三個問題：

• TODO 在 source 不會被 prioritize（產品 / 專案管理工具看不到 source 內的 TODO）
• FIXME 在 source 容易被忽略（讀的人會想「不是我寫的不是我的問題」）
• HACK / XXX 警告只在第一次讀時有效、第二次讀的人會麻木

問題嚴重需要立刻處理 → 開 ticket、commit fix；不嚴重可以等 → 開 backlog ticket、source 別寫。把待辦項從 source 搬到 issue tracker、會被真正當成「待辦」處理。

反模式 4：把 PR description 抄一份進 source

正向概念：PR description 是「這次提交的時空快照」、source code doc 是「持續適用的當前契約」。兩者描述的是同一段 code 在不同時序下的不同切面、各自有對應的家。

1/// 這個 function 是為了支援新的 multi-currency 結帳流程。
2/// 詳細需求見 PR #4521 與設計文件 https://wiki.../...
3/// 業務需求：客戶可以混合多幣別商品結帳，結帳當下統一換算成 settlement currency。
4/// QA 已驗證 5 種主要幣別組合 + 邊界 case。
5void multiCurrencyCheckout() { ... }

PR description 該寫的內容（業務脈絡、設計連結、QA 範圍）抄進 source、會讓 source 凍結在「這次新增時的時空狀態」——半年後 PR 已經是歷史、連結可能失效、QA 範圍可能擴展、但 source 還停在那一刻。PR description 留在 PR、source 只寫 function 當前的對外契約。

Git blame archaeology workflow

當 source code doc 跟 commit message 各司其職時，考古工作流會變得清晰：

 1讀者看到一段 code 不懂為什麼這樣寫
 2  ↓
 3先看 source code doc
 4  ↓
 5不夠 → 跑 git blame
 6  ↓
 7找到引入這段 code 的 commit
 8  ↓
 9讀 commit message
10  ↓
11不夠 → 點進去看完整 PR / issue

這個工作流要能順利跑，前提是：

1. commit 顆粒度合理——一個 commit 一個邏輯改動，不要「fix typo + refactor + add feature」混在一起，否則 blame 出來看到一個改 50 個檔案的 commit，message 寫 “stuff”，等於沒線索
2. commit message 寫清楚動機——不是「changed X」（git diff 看得出來），而是「changed X because Y」
3. 重大決定用 PR 描述補充——commit message 太長不適合塞長文，PR description 是放長文的地方

如果這三點做到，未來讀 code 的人有一條清楚的考古路徑，不必逼 source code doc 背所有歷史。

一個分配工具

決定一條資訊放哪時，問三個問題：

1. 「未來讀者不知道這條會做錯決定嗎？」
   • 是 → source code doc
   • 不是 → commit message
2. 「這條描述的是當前的行為，還是某次轉移？」
   • 當前行為 → source code doc
   • 某次轉移 → commit message
3. 「Code 改了，這條會不會 outdated？」
   • 不會（描述當前狀態）→ source code doc
   • 會（描述特定時間點）→ commit message

三個問題收斂到同一個直覺：「凍結在過去」屬於 commit、「持續適用」屬於 source。

邊界：什麼時候 source 還是該帶歷史脈絡

「歷史進 commit、契約進 source」是預設、但有些情境 source 還是該保留歷史脈絡——共通特徵是「未來讀者不知道這段歷史會做錯決定」：

• 看似怪、但有非顯然原因的寫法：「刻意不 retry、payment gateway 是非冪等」——下個維護者順手加 retry 會出事
• 跟非預期外部行為對齊的 workaround：「拆兩步 query 避開 SQLite 32-bit Android 的 integer overflow（issue #1234）」——讀者重構時會想「為什麼不一次查」
• 保留某段 code 的合規 / 法務原因：「依 GDPR 留 30 天可恢復、不是直接刪」——縮短到 7 天會違反法規
• 效能調優的非顯然參數：「batch size = 32 是 production 跑出來的甜蜜點、改大會 OOM」——下次 review 看到「為什麼不開大」時得知道過去的實驗結果

判斷標準：「未來讀者不知道這條歷史就會做錯決定嗎？」答「是」就留在 source、答「不是」就留在 commit。

一句話 heuristic

把整個討論濃縮：

Source code doc 寫給「正要動這段 code 的人」、commit message 寫給「想知道為什麼當初這樣寫的人」。

寫東西之前先問：我寫這段，是要幫正要動 code 的人做對決定，還是要幫回顧歷史的人理解某次改動？兩個讀者要找的資訊不同，分成兩處寫，雙方都受惠。

收束：兩份文件協同，源頭就要分清楚

很多團隊抱怨「source code doc 太亂、commit message 沒人寫」，本質是這兩份文件的職責沒分清楚。Source 想包辦所有事就會充滿過時內容；commit message 沒人寫是因為「反正歷史會寫進 source」變成預設。

把兩者的職責分清楚，兩份文件都會變健康：

• source 變短、變精準：只寫當前契約，doc 不會 outdated
• commit message 被認真寫：因為它是某些資訊的唯一家
• 考古路徑清楚：blame → commit → PR 是可預期的回溯路徑

寫 doc / 寫 commit 是同一個技能的兩面。不要把任何一邊當成另一邊的替代品。

核心命題：doc 是塑造使用者決策的工具——寫不好的 doc 會反向誤導使用者選錯路。 設計原則：把資訊放在能表達它的最低層次（名稱 / 型別 / 介面 doc / 實作 doc / 範例與測試）、上層留給「下層表達不了的剩餘」。

起點：doc 是塑造使用者決策的工具

API 設計者常忽略一件事：文件本身會塑造使用者的決策——讀者依照 doc 給的資訊選預設值、選呼叫方式、選用途，所以 doc 寫不好就會反向誤導使用者選錯路。

幾種常見的誤導模式：

• 把「需要明確選擇」的東西做成「最少打字的預設」（例如某些 stream / channel API 預設是單訂閱、多數 SQL column 預設 nullable）——使用者讀不到「該選什麼」的資訊，跟著預設走就出包
• 註解重複型別已說明的事，反而讓讀者懷疑「型別是不是不夠精確」
• 介面 doc 描述「目前實作怎麼做」而非「契約承諾什麼」——讓未來新實作以為要照抄
• 用憑想像的業務動機補完，後人讀了當真，反向影響其他相關決策

這些問題不是「沒寫 doc」，而是「寫了誤導的 doc」。要寫出不誤導的 doc，得先想清楚每個位置該放什麼資訊。

設計原則：資訊應該存在最低能表達它的層次

讀者讀一個 function 的閱讀順序：

1. 看簽章（名稱、參數、回傳型別）
2. 讀 doc comment
3. 跳進實作
4. 找範例 / 測試

每往下一層，閱讀成本就高一級。設計 doc 的原則：

能用上層表達的資訊，就不要往下層放。

對應的職責劃分：

把資訊放在能表達它的最低層次，能讓上層 doc 更精簡、更精準。

Layer 1：名稱與型別簽章

強型別語言下，型別是文件的一部分。很多 doc 內容本來就該由型別承擔。

用型別取代「參數說明」

1// 弱：依賴 doc 警告
2/// [quantity] 必須為正整數
3void increase(int quantity) { ... }
4
5// 強：型別本身就限制
6void increase(PositiveInt quantity) { ... }

1// 弱：String flag，靠 doc 說明可選值
2/// [mode] 可選值：'manual', 'auto', 'hybrid'
3void setMode(String mode) { ... }
4
5// 強：用 enum
6enum Mode { manual, auto, hybrid }
7void setMode(Mode mode) { ... }

當型別能表達約束時，不要用 doc 重複表達——doc 是約束的弱形式（編譯不檢查、IDE 補全不提示），把 doc 當主要 enforcement 等於放棄型別系統的力氣。

用命名取代「這個參數做什麼」

1// 弱：positional argument，靠 doc 解釋
2/// [a] 是基準值，[b] 是新值
3void update(int a, int b) { ... }
4
5// 強：named argument 自說明
6void update({required int from, required int to}) { ... }

update(from: 5, to: 10) 的呼叫端比 update(5, 10) 清楚得多，且不需要任何 doc。

用回傳型別表達失敗模式

1// 弱：可能失敗，靠 doc 說「失敗時回傳 null」
2/// 找不到時回傳 null
3User getUser(String id) { ... }
4
5// 強：型別本身表達 optionality
6User? getUser(String id) { ... }
7
8// 更強：分清 null 跟 error
9Result<User, NotFoundError> getUser(String id) { ... }

簽章已經表達清楚的事，doc 不必再寫。

命名要表達意圖，不是實作

1// 弱：implementation-leaking 命名
2List<Item> getCachedItems() { ... }
3
4// 強：意圖命名
5List<Item> getItems() { ... }

「Cached」這個字洩漏實作（用了 cache）。如果之後改成不 cache，名字就要改、所有 caller 也要改——但業務語義並沒變。命名應該反映「呼叫者想要什麼」，不是「實作怎麼做」。

展開閱讀：型別取代 doc 的收益曲線——整理 null safety / enum / wrapper / Result / typestate 各自能消除哪類 doc、以及型別表達不了的剩餘部分（業務動機、性能、副作用、時序契約）。

Layer 2：介面 doc

介面 doc 是契約（contract）——對所有實作的承諾。它的讀者有兩類：

1. 使用者：「我呼叫這個會發生什麼？需要注意什麼？」
2. 實作者（包括寫 mock、寫新版實作的人）：「我必須遵守哪些規則？」

兩類讀者都不該為了讀懂契約而去讀任何單一實作。

該寫的：契約承諾、行為保證、隱性需求

• 何時 throw / 回傳特殊值：「找不到時 throw NotFoundException」
• 副作用：「呼叫後 currentUser 會被清空」
• 同步 / 非同步保證：「呼叫後資料庫立即一致；快取要等下一次 refresh」
• 執行順序保證：「listener 觸發順序不保證」
• 業務規則（只在有實際業務需求時寫，且要有來源）：「會員價只能用 wallet 付款」

容易誤入介面 doc 的內容（屬於型別、實作或他處）

介面 doc 的職責是契約描述——所以「型別簽章已說的事」「特定實作怎麼做」「沒來源的業務動機」分屬其他層次（型別、實作 doc、issue tracker）、寫進介面 doc 反而稀釋契約本身的能見度。三個典型誤入：

1. 型別已表達的內容（屬於型別簽章）

1// 冗：
2/// 回傳 User，找不到時為 null
3User? findUser(String id);
4
5// 簡：型別已說明，doc 留白或寫業務動機
6User? findUser(String id);

2. 當前實作的細節（屬於實作 doc）

1// 冗：洩漏實作
2/// 內部用 HashMap 存儲，O(1) 查詢
3User? findUser(String id);
4
5// 簡：純契約
6User? findUser(String id);

實作細節寫在介面 doc 會誤導實作者「這個契約規定要用 HashMap」。如果未來有人寫一個用 B-tree 的實作，是合法的，但讀 doc 會以為違反契約。

3. 憑想像補完的業務動機（屬於 issue tracker / 不寫）

1// 冗（且可能錯）：
2/// 為了符合 PCI-DSS 規範，這裡不能 log 完整 cardNumber
3String maskCardNumber(String cardNumber);
4
5// 簡（沒來源就只寫可觀察事實）：
6/// 回傳遮罩後字串，僅保留尾 4 碼
7String maskCardNumber(String cardNumber);

業務動機要有來源（規範文件、PM 決策、incident 紀錄）才寫；猜的不要寫。猜的動機被當真會反向影響後續決策——讀者拿這條沒來源的猜測當依據、推到「既然是因為 PCI-DSS、那 X 也要這樣處理」、就把錯誤論述擴散到下游。

介面 doc 越精簡越能被讀完

很多人覺得「寫得詳細才負責任」，結果介面 doc 三段五行，讀完也記不住。好的介面 doc 通常只有 2-4 行：

1/// 從本地購物車移除指定商品
2///
3/// 找不到對應品項時不做事；不會拋例外。
4void removeFromLocalCart(CartItem item);

第一行說 what、第二行說 edge case。寫到這就停。「指定商品」怎麼比對？無關契約，去看實作。

Layer 3：實作 doc

實作 doc 的職責跟介面 doc完全不同：

• 介面 doc：對外契約，所有實作共通
• 實作 doc：這個實作特有的細節

該寫的：實作特有的 invariant、workaround、tradeoff

 1// 該寫：實作特有的 invariant
 2@override
 3void increaseItemQuantity(CartItem item) {
 4  // 順序關鍵：先 set lastChangedItem 再動 list，
 5  // 因為訂閱 localCartItems 的 worker 會在 list 變動時讀 lastChangedItem
 6  lastChangedItem.value = item;
 7  localCartItems[index] = ...;
 8}
 9
10// 該寫：bug workaround
11// Workaround for SQLite issue #1234: integer overflow on 32-bit Android,
12// 拆成兩步 query 避開
13final ids = await db.rawQuery('SELECT id FROM ...');
14return await db.query('items', where: 'id IN (${ids.join(",")})');
15
16// 該寫：性能 tradeoff
17// 用 LinkedHashMap 而非普通 Map：插入 1k 次後查詢效能差 3-5 倍
18final cache = LinkedHashMap<String, Item>();

這些都是**讀實作 code 也看不出「為什麼要這樣」**的決定，需要 doc 解釋。

契約只寫一處：實作不重複介面已寫的規則

實作 doc 的職責跟介面 doc 互補——契約描述歸介面層、實作層只補「該實作的特殊性」。同一條契約規則寫第二次（在實作層複述介面已寫的承諾）會破壞「契約只寫一次」原則：規則改的時候要同步兩處、少改一處就出現自相矛盾的文件、讀者看到也分不清以哪份為準。

1// 不該寫：介面 doc 已寫的規則，實作不再重複
2@override
3// 移除不視為「最後變更」，不更新 lastChangedItem
4void removeFromLocalCart(CartItem item) {
5  localCartItems.remove(item);
6}

「移除不更新 lastChangedItem」是契約、介面層已寫。

如果擔心未來維護者誤以為「作者忘了寫」，留一個指向介面的最小提示比複述整條規則更安全：

1@override
2// 行為見 ICartService.removeFromLocalCart
3void removeFromLocalCart(CartItem item) {
4  localCartItems.remove(item);
5}

不重複規則，只指向真相來源。

Negative-space documentation

實作 doc 偶爾要寫「為什麼這裡刻意沒寫某段程式」。這類 doc 防的是「未來維護者順手補上」：

1void processPayment(Payment p) {
2  // NOTE: 這裡刻意不 retry —— payment gateway 是非冪等，
3  // retry 會造成重複扣款。失敗一律拋給上層人工處理。
4  return _gateway.charge(p);
5}

沒這條註解，下個維護者看到網路 retry 是常見做法，可能會「順手加上」造成事故。

negative-space doc 用得好可以避免事故；用得多會變成處處防禦性註解，閱讀體驗變差。原則：這個「刻意沒做」的決定，是不是違反讀者的合理直覺？ 違反才寫。

Layer 4：範例與測試

複雜 API 的最後一層 doc 是可執行範例。

何時用 example：

• API 有多個正交參數，組合起來很多種用法
• 抽象描述比看程式碼難懂
• 邊界 case 用文字描述模糊（「如果 collection 是空、且 timeout 為 zero、且 retries 為 0…」）

何時不用 example：

• API 用法只有一種、簽章已說清
• 用法跟名稱字面意義一致

測試也是 doc。命名好的測試比 example 更有價值——不會 outdated（測試會跑、example 不會），且涵蓋 edge case。

1test('returns null when item not in cart', () { ... });
2test('decreases quantity when item exists with quantity > 1', () { ... });
3test('removes item when quantity reaches 0', () { ... });

讀者看 function 不確定行為時，跳到對應 test file 比讀冗長 doc 快——測試案例的命名直接告訴你支援哪些 case，並且每個案例都有可執行的具體輸入輸出。

展開閱讀：測試命名作為文件——測試是少數會自我驗證的文件、把命名寫成可執行 spec 條目就能取代不少 doc 的職責。

常見反模式

反模式 1：用 doc 取代不好的命名

正向概念：命名是契約的最強形式、doc 是命名表達不了的剩餘部分的家。命名先到位、doc 才有空間寫真正重要的事。

1// 反：靠 doc 補救命名
2/// 處理訂單，但只在訂單狀態為 pending 時做事
3void handle(Order o);
4
5// 正：命名表達意圖
6void handlePendingOrder(Order o);

把 doc 當成命名失敗的補丁有兩個問題：(1)「需要讀 doc 才能用對」的 function 在 IDE 自動補全 / 快速瀏覽時看不到 doc、誤用機率高；(2) 命名其實沒變、別人改 code 時 doc 會跟不上、補丁本身又 outdated。「需要 doc 才能用對」通常是命名沒到位的訊號。

反模式 2：過度註解

正向概念：doc 是稀缺資源——讀者注意力的預算有限、把 doc 留給「值得花注意力讀」的事項。

 1// 反：句句都是 noise
 2class User {
 3  /// User 的 ID
 4  String id;
 5  /// User 的名字
 6  String name;
 7  /// User 的 email
 8  String email;
 9}
10
11// 正：欄位名清楚就不寫
12class User {
13  String id;
14  String name;
15  String email;
16}

「User.name 是 User 的名字」屬於命名已表達的訊息、寫進 doc 只是 redundant noise。整份 code 充斥這類 doc 會稀釋訊號——讀者習慣性 skip 所有 doc 之後、連真正重要的 invariant 跟 edge case 也會被一起跳過。

反模式 3：過去式 doc

正向概念：source code doc 描述「現在這份 code 在做什麼」、commit message 描述「那一刻為什麼要改」。兩種讀者要找的資訊不同、各歸各的家。

1// 反：寫給歷史
2/// 修了 issue #123 的 race condition
3void process() { ... }
4
5// 正：寫給未來讀者（保留 fix 的關鍵 invariant 即可）
6void process() {
7  // 必須在持有 lock 內 call observer，避免 observer 看到中間狀態
8  ...
9}

「修了什麼 bug」凍結在過去某一刻、屬於 commit message / changelog；「目前必須持有 lock」是契約限制、屬於 source code doc。把過去式直接塞進 source 等於用 source 重做一份 git log——但 git log 已經存在、且結構化、可搜尋、有 author / timestamp。

展開閱讀：Commit message vs source code doc——時序敏感的資訊（為什麼這次改、考慮過什麼方案）放 commit、持續適用的契約放 source、配合 git blame 工作流讓考古路徑清楚。

反模式 4：同一條規則多處寫

正向概念：契約由介面層獨家承載、其他層引用即可。規則只有一個 SSoT（Single Source of Truth）、修改成本才可控。

1// 反：規則寫三處
2// 介面：「取消訂單後 3 天內不能重新下單」
3// 實作：「取消後 3 天內不能重新下單」
4// 測試：「驗證取消後 3 天內不能重新下單」
5
6// 正：規則寫一處（介面），其他指向
7// 介面：「取消訂單後 3 天內不能重新下單」
8// 實作：（無 doc）
9// 測試：test('cannot reorder within 3 days of cancellation')

一條規則複製到三處看起來保險、但會在改規則時暴露代價：要同步修三處、漏改一處就出現自相矛盾的 doc、讀者讀到不一致的版本反而會懷疑「以哪份為準」。把規則收斂到單一介面、其他層指向（測試命名 / 實作註解 // 行為見 ...）就夠了。

反模式 5：把語法選擇當成 doc 內容

正向概念：doc 描述業務目的跟行為契約——讀者要的是「這個 function 做什麼」、不是「為什麼用這個語法寫」。

 1// 反：寫實作層次的選擇細節
 2/// 用 Dart 3 的 record pattern destructure，比 .$1 / .$2 可讀
 3void handle((int, int) event) {
 4  final (a, b) = event;
 5  ...
 6}
 7
 8// 正：寫業務動機 / 行為契約
 9/// 處理 (timestamp, value) 對的批次更新
10void handle((int, int) event) { ... }

「為什麼用某語法」屬於 commit message / PR review 的討論記錄、不屬於 source code doc——換個語法寫法、業務行為沒變、但 doc 卻會 outdated。語法選擇的 why 在 git log / PR description 找得到、不需要 source 背這份歷史。

反模式 6：用 doc 警告使用者「請別這樣用」

正向概念：能用型別 / API 設計禁掉的誤用、把它編進型別系統；doc 警告留給型別表達不了的使用情境（時序、跨方法 invariant、執行環境）。

1// 反：靠 doc 警告
2/// **不要**直接修改回傳的 list，會造成內部狀態不一致
3List<Item> getItems();
4
5// 正：型別 / API 設計阻止誤用
6List<Item> getItems() => List.unmodifiable(_items);
7// 或回傳 Iterable / immutable 集合型別

doc 警告的執行力靠使用者「願意讀並且記住」、型別約束則是編譯期強制——當失敗成本高（內部狀態被破壞）、保護機制就值得從 doc 升到型別。型別表達不了的使用情境（例如「必須在 main isolate 呼叫」）才是 doc 警告該守的範圍。

API 設計層面：doc 之外的塑造工具

doc 寫得再好，API 設計本身會更直接塑造使用者行為。要讓使用者選對，從設計層下手比寫 doc 有效。

預設值要選「多數情況下對的」

1// 預設導向受限選項：使用者忘了選通用版本就出錯
2StreamController<int> ctrl = StreamController();  // single
3
4// 預設導向通用選項：忘了選受限版本不會出錯
5StreamController<int> ctrl = StreamController.broadcast();
6// 受限版本要顯式選 .singleSubscription()

當預設造成的失敗成本高、失敗模式又不易察覺、把多數人實際需要的選項變成預設、能消除整類「忘了選」的事故。doc 警告的執行力靠「使用者讀到並記住」、規模一大就守不住——把保護從約定升到結構。

把選擇從 default 取消（用型別禁掉）

1// 弱：靠 doc 說「不該直接呼叫，請用 X」
2@protected
3void internalMethod() { ... }
4
5// 強：型別系統禁掉
6class _InternalImpl { void method() { ... } }

能用 visibility / sealed / private 收掉的「請別這樣用」、把它收進型別系統——比起 doc 提示、語言層級的禁用是無條件強制的、且不會在大型重構時被遺漏。

Builder / fluent API 取代多參數

1// 弱：positional / named 多參數，靠 doc 解釋
2Request build(String url, [Map<String, String>? headers, Body? body, int timeout = 30]);
3
4// 強：fluent API 自說明
5Request.builder(url)
6  .header('Accept', 'json')
7  .body(payload)
8  .timeout(Duration(seconds: 30))
9  .build();

fluent API 的 method 名直接表達意圖，不需要 doc 解釋每個參數做什麼。

寫 function doc 的 checklist

寫一個 function doc 前，跑這個 checklist：

• 這條資訊型別能不能表達？ 能 → 改 type，不寫 doc
• 這條資訊命名能不能表達？ 能 → 改名，不寫 doc
• 這條資訊是契約還是實作細節？ 契約 → 介面 doc / 實作 → 實作 doc
• 這條規則是不是已經寫在介面 doc？ 是 → 實作不重複
• 這個業務動機有沒有來源？ 沒有 → 不寫，只寫可觀察事實
• 這個 doc 在描述什麼時候出問題？ 是 → 寫得明確（throw / null / edge case）
• 沒有這條 doc，讀者會誤判嗎？ 不會 → 不寫
• 同一條規則我寫了第二次嗎？ 是 → 砍一處，留一處

過完 checklist 留下的 doc 通常很短——這是好現象。

一句話 heuristic

把整個討論濃縮：

doc 是「型別、簽章、命名、結構都表達不了的剩餘資訊」的家。

寫 doc 之前先問：

• 能用型別表達嗎？
• 能用命名表達嗎？
• 能用結構（fluent API、enum、sealed class）表達嗎？

三題都答「不能」、而且使用者不知道會出錯——這時才需要 doc。

這個原則的 corollary：型別系統越強的語言、function doc 也越能寫得短。如果發現 Dart / TypeScript / Rust 的 function doc 寫得跟 Python 一樣長、多半有東西可以下移到型別。

何時 doc 還是該寫得詳細

「能少寫就少寫」是預設、但有些情境 doc 必須寫得詳細——這些是型別跟結構覆蓋不到的場景：

• 跨方法 protocol：「呼叫 reserve 之後必須在 X 內呼叫 commit 或 release」——typestate 能部分表達但寫法繁瑣、多數情況靠 doc 是合理的
• 時序契約：「寫入後最多 1 秒內 read replica 可見」「retry 5 次後放棄」——跨呼叫、跨時間的契約、型別表達不了
• 副作用 / 對外部系統的影響：「會寫入 audit log」「會發 webhook」——caller 需要知道才能規劃整體流程
• 業務規則 + 有來源：「會員價只能用 wallet 付款（業務需求 #1234）」——有出處的業務動機要寫、避免後人誤刪
• 效能契約：「O(log n) 查詢；不適合在熱迴圈呼叫」——caller 要根據這個資訊選用法

「短」不是目標、「精準」才是。把該下移的下移到型別、剩下的就值得詳細寫。

收束：doc 設計就是 API 設計

回到開頭——doc 寫不好會誤導使用者。但更深一層的觀察是：「需要寫很多 doc 才能用對」本身就是 API 設計的紅旗。

好的 API 用最少的 doc 就能讓使用者用對：

• 命名直接表達意圖
• 型別表達合法輸入與失敗模式
• 結構（enum、sealed、builder）防止誤用
• 預設值導向多數情況下正確的選擇
• 殘餘的契約與 edge case 用簡短介面 doc 說明
• 實作特有的 invariant 用簡短實作註解說明

寫 doc 的時候同時問「這條 doc 想說的事，是不是該由 API 設計本身承擔？」——這個問題能讓你的 doc 跟 API 同時變更好。

核心命題：型別系統強化等於 doc 表達力轉移——很多 doc 內容應該下移到型別。 設計原則：能用型別表達的限制，不要用 doc 表達；doc 是型別表達不了的剩餘資訊的家。

本篇是 函式文件分層設計 的 Layer 1（名稱與型別簽章）展開——把「型別承擔哪些原本寫在 doc 的內容」拉成獨立主題討論。

起點：型別越強、doc 的職責範圍就越窄

「型別系統越強、function doc 也越能寫得短」——這是個普遍但不被刻意利用的現象。

當你看到一個 Dart / TypeScript / Rust 的 function doc 寫得跟 Python / JavaScript 一樣長、多半有東西可以下移到型別。把可下移的內容下移、doc 表面變短、實質上的好處更深：

• 編譯期被檢查——型別說的事不會 outdated（doc 會）
• IDE 補全提示——使用者看到型別就懂、不用切到文件頁
• 重構時連動——改型別會逼所有 caller 跟著改、doc 改了沒人逼你檢查

這篇整理：哪些常見的 doc 內容能被型別取代、哪些下移了會破壞別的東西、以及型別越加越強時要怎麼平衡 ergonomic 跟表達力。

可被型別取代的常見 doc 內容

下面 8 類 doc 內容、共通特徵是「可以從 doc 約定升級成型別約束」——升級之後、保護從「靠使用者讀並記住」變成「靠編譯器強制」、執行力跟一致性都比 doc 強。每類列出弱（doc 約定）vs 強（型別約束）的對比。

1. 「必須是正整數」「必須非空」「必須在範圍內」

 1// 弱：依賴 doc 警告
 2/// [quantity] 必須為正整數（>= 1）
 3void increase(int quantity) {
 4  if (quantity < 1) throw ArgumentError(...);
 5}
 6
 7// 強：refinement type / value object
 8class PositiveInt {
 9  final int value;
10  PositiveInt(this.value) {
11    if (value < 1) throw ArgumentError(...);
12  }
13}
14void increase(PositiveInt quantity) { ... }
15
16// 最強（語言支援的話）：refinement types
17void increase(int quantity) where quantity > 0 { ... }

Dart 沒有 native refinement type，但用 wrapper class 一樣能達到「呼叫端要顯式建構合法值才能呼叫」的效果。validation 從「呼叫進入 function 後才檢查」前移到「建構 value object 時檢查」，contract 變成型別系統的一部分。

2. 「可能為 null」「找不到時回傳 null」

 1// 弱（前 null safety 時代）：
 2/// [name] 可為 null，[email] 不可為 null
 3class User {
 4  String? name;
 5  String email;
 6}
 7/// 找不到時回傳 null
 8User getUser(String id);
 9
10// 強（null safety）：
11class User {
12  String? name;       // 型別已說可為 null
13  String email;       // 型別已說不可為 null
14}
15User? getUser(String id);  // 型別已說可能找不到

Dart / TypeScript / Kotlin / Swift 的 sound null safety 把「可為 null」從 doc 約定升級成型別約定——升級之後、「[X] 可為 null」這類 doc 變成 redundant noise（型別已經精準說了、重複寫只是稀釋訊號、改型別時忘了同步 doc 還會誤導讀者）。

3. 「會 throw 某 exception」

 1// 弱：靠 doc
 2/// 找不到時 throw [NotFoundException]
 3/// 網路錯誤時 throw [NetworkException]
 4Future<User> getUser(String id);
 5
 6// 強：用 Result / Either / sealed class
 7Future<Result<User, GetUserError>> getUser(String id);
 8
 9sealed class GetUserError {}
10class NotFoundError extends GetUserError {}
11class NetworkError extends GetUserError {
12  final int statusCode;
13}

Result / Either pattern 把 error 從「invisible exception」升級成「型別簽章可見的回傳值」。Caller 必須處理（編譯不過 if not handled），不會漏掉 error path。

代價：寫法比 throw 多一些；不是所有 codebase 都採用這個 pattern。但對核心 service 介面值得。

4. 「合法值是 A、B 或 C」

1// 弱：String flag + doc
2/// [mode] 可選值：'manual'、'auto'、'hybrid'
3void setMode(String mode);
4
5// 強：enum
6enum Mode { manual, auto, hybrid }
7void setMode(Mode mode);

String flag 是「doc 約束代替型別約束」的最常見例子。改用 enum 之後：

• IDE 自動補全
• 拼錯立刻編譯錯
• 新增 / 刪除 mode 時所有 caller 編譯出錯（迫使你檢查每個地方該怎麼處理）

5. 「狀態 X 才能呼叫」

 1// 弱：靠 doc + 執行期檢查
 2/// 必須在 [open] 之後、[close] 之前呼叫；否則 throw [StateError]
 3void write(String data);
 4
 5// 強：typestate / phantom types（Rust 友善，Dart 較吃力）
 6class OpenConnection { void write(String data) { ... } }
 7class ClosedConnection { /* no write method */ }
 8
 9OpenConnection open() { ... }
10ClosedConnection close(OpenConnection conn) { ... }

typestate 把「必須在某狀態下才能呼叫」變成「那個狀態才存在那個方法」。Rust / Haskell 寫起來最自然；Dart / Java 可以用建構子分流模擬，但 ergonomic 較差。

對核心 lifecycle（connection、transaction、stream subscription）值得用；一般 service 不必。

6. 「兩個參數互斥」「某參數有時必填」

 1// 弱：positional args + doc
 2/// 同時提供 [token] 和 [credentials] 會 throw
 3/// 至少要提供一個
 4User auth(String? token, Credentials? credentials);
 5
 6// 強：sealed class 表達互斥
 7sealed class AuthMethod {}
 8class TokenAuth extends AuthMethod { final String token; }
 9class CredentialsAuth extends AuthMethod { final Credentials creds; }
10
11User auth(AuthMethod method);

「至少一個 / 至多一個 / 互斥」這類條件用 sealed class / discriminated union 表達。caller 看到型別就知道兩條路擇一，不需要 doc 說明組合規則。

7. 「這個 collection 是 read-only / 不要修改」

 1// 弱：靠 doc 約定
 2/// 不要修改回傳的 list
 3List<Item> getItems();
 4
 5// 強：immutable collection 型別
 6List<Item> getItems() => List.unmodifiable(_items);
 7// 或：
 8Iterable<Item> getItems() => _items;  // Iterable 不暴露 mutation
 9// 或（用 built_collection）：
10BuiltList<Item> getItems();

「請別修改」doc 警告靠的是「使用者願意讀且記住」，型別約束是強制的。

8. 「測量單位」（公里 vs 英里、秒 vs 毫秒）

1// 弱：靠 doc 標單位
2/// [timeout] 單位：毫秒
3void setTimeout(int timeout);
4
5// 強：用語義型別
6void setTimeout(Duration timeout);
7setTimeout(Duration(seconds: 30));  // 不需要記得是哪個單位

混淆單位是真實事故來源（Mars Climate Orbiter 級別的）。Duration / Money / Distance 等領域 wrapper 型別把單位編進型別系統，呼叫端不會傳錯。

型別表達不了的部分（doc 仍是該寫的家）

把可下移的下移之後，doc 還剩什麼？這些是型別表達不了的：

1. 業務動機 / 為什麼這個契約存在

1/// 會員價只能用 wallet 付款
2/// （業務規則：會員價是 wallet 餘額的折扣回饋）
3void chargeMemberPrice(Member m);

「為什麼只能用 wallet」是業務規則，不在型別系統的射程內。這類有來源的業務動機仍然要寫 doc——但要有來源，不是憑想像。

2. 性能特性

1/// O(log n) 查詢；插入 O(n)
2T find(int id);

Big-O / 延遲特性 / 記憶體 footprint 等性能契約，型別表達不了。如果這個性能特性是 caller 需要知道才能正確選用（例如「這個 method 不適合在迴圈裡呼叫」），就要寫進 doc。

3. 對外部系統的副作用

1/// 寫入 audit log（第三方系統，可能延遲到資料庫）
2void recordTransaction(Tx tx);

跟外部系統的互動（log、analytics、cache invalidation、cloud sync）是型別表達不了的副作用。caller 需要知道這些副作用才能規劃整體流程。

4. 時序契約（eventually consistent、retry 行為）

1/// 寫入後最多 1 秒內所有 read replica 會看到新值
2Future<void> updateProfile(Profile p);

「最多多久內 consistent」「失敗多少次後放棄 retry」「某事件多久觸發一次」——這類跨呼叫、跨時間的契約，型別系統無法表達。

5. 使用情境的限制（threading / isolation）

1/// 必須在 main isolate 呼叫；否則 throw `IsolateError`
2void registerPlatformChannel(String name);

「哪個 thread / isolate / context 才能呼叫」這類資訊，多數型別系統無法強制（Rust 的 Send/Sync 是少數例外）。

6. 跨方法 invariant

1/// 跟 [withdraw] 配對使用：每次 [reserve] 之後必須對應一次
2/// [withdraw] 或 [release]，否則餘額會被 reserved 卡住
3void reserve(Decimal amount);

「呼叫了 X 之後必須在 Y 時間內呼叫 Z」這類跨方法的 protocol，typestate 能部分表達但寫法繁瑣，多數情況靠 doc 是合理的。

各語言實際範例

Dart：null safety 的影響

Dart 2.12 引入 sound null safety 後，至少消除了 30% 的 doc 內容——不再需要寫「可為 null」「不可為 null」「null 時的行為」。

升級前後對比：

 1// 前（Dart 2.10）
 2/// [name] 可為 null
 3/// 找不到時回傳 null
 4class User {
 5  String name;  // 實際可能為 null，doc 提醒
 6}
 7User findUser(String id);  // 實際可能為 null
 8
 9// 後（Dart 3.x）
10class User {
11  String? name;  // 型別說明
12}
13User? findUser(String id);  // 型別說明

如果你的 Dart codebase 升了 null safety 但 doc 還在寫「可為 null」之類字句，說明還沒充分利用型別系統的成果。

Rust：ownership 與 borrow 消除一整類 doc

1// C 風格：靠 doc 警告
2/// 注意：caller 必須在 buffer 釋放前完成讀取
3/// 不要把 buffer 傳給其他 thread
4fn process(buffer: *const u8, len: usize);
5
6// Rust：型別表達
7fn process(buffer: &[u8]);  // borrow，編譯期保證 lifetime
8fn process_owned(buffer: Vec<u8>);  // own，move 後 caller 不能再用
9fn process_shared(buffer: Arc<[u8]>);  // 跨 thread 安全共享

Rust 的 ownership / borrow 系統把記憶體管理 / 並發安全相關的 doc 幾乎完全變成型別。寫 Rust 的 function doc 多半短得驚人——大部分 contract 已經編進簽章。

TypeScript：discriminated union 取代條件 flag doc

 1// 弱：靠 doc 解釋 flag 之間的關係
 2/**
 3 * @param type 'success' or 'error'
 4 * @param data 當 type='success' 時必填，否則為 null
 5 * @param error 當 type='error' 時必填，否則為 null
 6 */
 7interface Response {
 8  type: string;
 9  data?: any;
10  error?: string;
11}
12
13// 強：discriminated union
14type Response =
15  | { type: 'success'; data: ResponseData }
16  | { type: 'error'; error: string };
17
18// 使用時 TypeScript narrowing：
19if (response.type === 'success') {
20  console.log(response.data);  // 型別已知是 ResponseData
21} else {
22  console.log(response.error);  // 型別已知是 string
23}

discriminated union 把「flag 跟其他欄位的關聯」編進型別。這比 doc 警告強多了。

收益曲線：什麼時候強型別開始邊際遞減

把所有可下移的 doc 都下移，是不是型別越強越好？不是。型別強化有邊際成本：

實務 sweet spot 通常落在 1-4 之間。5-6 在 systems / safety-critical 程式碼有意義，一般 app 加進去 ergonomic 變差，回收不到。

一個 review 的問題：「這條 doc 能變型別嗎？」

review code 看到 doc 時，問三個問題：

1. 這條 doc 描述的是輸入合法範圍嗎？
   • 是 → 能不能用 wrapper type / refinement / enum 表達？
2. 這條 doc 描述的是回傳的可能性（null、error、特殊值）嗎？
   • 是 → 能不能用 nullable / Result / sealed class 表達？
3. 這條 doc 描述的是「這時候才能呼叫」嗎？
   • 是 → 能不能用 typestate / 不同型別的方法分流表達？

任一答案是「能」、先試型別。如果型別寫起來 ergonomic 不好（例如 wrapper class 太多、call site 變難讀）、再退回 doc——「先試型別」比「預設寫 doc」更能逼出可下移的部分。

一句話 heuristic

把整個討論濃縮：

doc 是「型別表達不了的剩餘資訊」的家——型別越強、剩餘越少。

寫 doc 之前先問「能用型別表達嗎」。能 → 改型別。不能 → 寫 doc，但只寫那條型別表達不了的部分（業務動機、性能、副作用、時序契約、跨方法 protocol）。

收束：型別系統升級是文件設計升級的契機

每一次語言升級（Dart 2 → 3、TypeScript 加新型別功能、Rust 穩定新 lifetime feature），都是重新檢視既有 doc 的機會：

• 哪些 doc 可以下移到新引入的型別功能？
• 下移之後，剩下的 doc 是不是更精準了？
• 是不是有新的型別組合能表達以前只能靠 doc 的契約？

把語言升級當成 doc 整理的契機，不只是「換個編譯器」。程式碼品質的關鍵改善往往來自把約定升級為約束——doc 是約定，型別是約束。約定靠人記住，約束靠工具強制。每次升級都是一次「把約定變約束」的機會窗口。

寫到「三行 doc 解釋一個 function 的合法輸入範圍」這個訊號時、自問：「這三行能不能變成型別簽章？」——多半可以。

核心命題：測試是少數會自我驗證的文件——名稱說的事如果跟實際行為不符，CI 會炸。 設計原則：測試命名應該讓「跳到測試檔讀名字」就能取代讀 doc。

本篇是 函式文件分層設計 的 Layer 4（範例與測試）展開——把「測試命名作為可執行 spec」這個職責拉成獨立主題討論。

起點：被 CI 強制同步的 doc

source code 的 doc comment 有個結構性缺陷：寫得再好，code 改了 doc 沒改，doc 就在說謊。沒有任何工具強制 doc 跟 code 同步。

測試是少數例外。一個命名為 removes_item_when_quantity_reaches_zero 的測試，如果實際上 quantity 到 0 時沒移除，測試會失敗、CI 會擋下 commit。測試名稱跟實際行為的一致性是被 CI 強制的——這讓測試成為會自我驗證的文件。

當你把這個性質有意識地利用起來，測試就不只是 regression 工具，而是可執行的 API 規格。

測試命名的三種主要模式

被測單元的契約大致分三類：「在某狀態下回傳什麼」「某操作會做什麼」「何時 throw / 失敗」——對應到測試命名也分三類 pattern。每類 pattern 的命名格式不同、負責驗證契約的不同切面。

模式 1：state-based（狀態描述）

「在某個狀態下，呼叫 X 會回傳 / 變成什麼」。

1test('returns_null_when_user_not_found', () { ... });
2test('returns_empty_list_when_no_items_match', () { ... });
3test('returns_cached_value_on_second_call', () { ... });

適合：query / read-only 操作。

模式 2：scenario-based（情境描述）

「當某條件成立時，操作會做什麼」。

1test('removes_item_when_quantity_reaches_zero', () { ... });
2test('decreases_quantity_when_item_exists_with_quantity_above_one', () { ... });
3test('updates_lastChangedItem_on_addItem', () { ... });
4test('does_not_update_lastChangedItem_on_removeItem', () { ... });

適合：command / mutation 操作。注意 does_not_X 形式——negative assertion 也該寫進名字，這正是契約的一部分。

模式 3：failure-mode（失敗模式描述）

「在某輸入 / 狀態下，會 throw / error / 失敗」。

1test('throws_NotFoundException_when_id_does_not_exist', () { ... });
2test('throws_StateError_when_called_after_dispose', () { ... });
3test('returns_error_when_network_unavailable', () { ... });

適合：error path、edge case。失敗模式是 doc 最容易漏寫的部分，但對 caller 最關鍵。

Group 結構作為命名空間

巢狀 group 提供了「主題 → 操作 → 情境」的階層命名空間，比扁平命名更易讀：

 1group('CartService', () {
 2  group('addItem', () {
 3    test('appends_when_item_not_in_cart', () { ... });
 4    test('increments_quantity_when_same_item_exists', () { ... });
 5    test('updates_lastChangedItem', () { ... });
 6  });
 7
 8  group('removeItem', () {
 9    test('removes_when_item_exists', () { ... });
10    test('does_nothing_when_item_not_found', () { ... });
11    test('does_not_update_lastChangedItem', () { ... });
12  });
13
14  group('decreaseQuantity', () {
15    test('decreases_when_quantity_above_one', () { ... });
16    test('removes_item_when_quantity_reaches_zero', () { ... });
17  });
18});

讀者掃過 group 結構，立刻知道 CartService 對外提供哪些操作、每個操作有哪些行為承諾——這是這個 service 的 readable spec。

工具支援：好的 IDE / test runner 會把 group 結構顯示為樹狀，跑測試時的輸出也帶階層。把這個視覺結構利用好，測試 console 本身就是 doc 瀏覽器。

把 tests 當 readable spec 的閱讀流程

當你不確定一個 function 的行為時，閱讀順序通常是：

1. 看簽章 → 知道 what / takes / returns
2. 讀 doc → 知道契約、edge case
3. 看實作 → 知道 how
4. 找測試 → 看具體 case

但如果測試命名做得好，順序可以對調：

1. 看簽章
2. 跳到對應 test file，掃 group + test names → 看 API 支援哪些 case、各 case 的承諾
3. 不夠才回去讀 doc / 實作

這個順序的優勢：

• 測試名是被驗證過的事實，doc 是聲明（可能 outdated）
• 測試名涵蓋 edge case，比 doc 完整
• 跳到測試只要一個快捷鍵（多數 IDE 有 “Go to Test” 命令）

當團隊習慣這個閱讀順序，doc 寫多寫少的壓力就會減輕——很多 edge case 直接讓測試說明，doc 留給「測試也表達不了」的部分（業務動機、隱性需求）。

反模式

反模式 1：test_ 前綴 + 模糊主題

正向概念：測試名字的每個 token 都該承載資訊——前綴或主題詞如果讀者一眼推不出「在驗什麼」、就是浪費 token budget。

1// 反：純 noise
2test('test_user', () { ... });
3test('test_user_2', () { ... });
4test('test_user_creation', () { ... });
5
6// 正：說明具體行為
7test('creates_user_with_default_role_when_role_omitted', () { ... });

test_ 前綴是工具年代留下的習慣（早期某些 framework 靠它識別測試 method）；現代 framework 用 annotation / 函式簽章識別、前綴變成純 noise。模糊的主題（test_user、test_creation）等於沒命名——讀者必須跳進 body 才能分辨兩個 test 在驗什麼、命名的 doc 價值消失。

反模式 2：實作洩漏的命名

正向概念：測試驗的是對外可觀察的契約——換實作而契約沒變、測試應該繼續通過、命名也不該需要改。

1// 反：洩漏實作（用 hashmap、用 cache）
2test('uses_hashmap_for_lookup', () { ... });
3test('caches_result_after_first_call', () { ... });
4
5// 正：描述對外可觀察行為
6test('returns_value_in_O_1_for_existing_key', () { ... });
7test('subsequent_calls_return_same_instance', () { ... });

命名洩漏實作後、重構（換 hashmap 為 trie、移除 cache 改用 lazy init）會逼迫測試一起改名——但對外行為其實沒變。一個良好的契約測試、應該在 codebase 大改造後仍能驗證「行為是否還是當初承諾的樣子」、命名洩漏實作會破壞這個性質。

反模式 3：描述「怎麼做」而非「做什麼」

正向概念：測試名描述「被測單元的契約」、test body 描述「測試怎麼寫」——分配給對應的位置、讀者跳到名字看契約、跳到 body 看細節。

1// 反：描述測試怎麼跑（過程）
2test('mocks_db_and_calls_findUser_then_asserts_result', () { ... });
3
4// 正：描述被測 function 的行為
5test('returns_null_when_user_not_found', () { ... });

把「mocks_db_and_calls_X」寫進名字、讀者拿到的是「測試怎麼寫的過程」、不是「被測單元承諾什麼」——但讀 spec 想知道的是後者。「怎麼寫」放 test body、「驗證什麼契約」放名字、兩種讀者都得益。

反模式 4：assertion-style 命名

正向概念：測試名是業務語義的入口、不是 assertion 框架的字面映射——讀者讀名字想推「業務上發生什麼」、不是「assert 用了哪個動詞」。

1// 反：assertion 寫在名字
2test('isFalse_when_disabled', () { ... });
3test('equal_when_same_input', () { ... });
4
5// 正：描述行為
6test('returns_false_when_feature_disabled', () { ... });
7test('returns_same_result_for_equivalent_inputs', () { ... });

isTrue、equal、isNotEmpty 是 assertion 動詞、不是行為描述。讀者讀 isFalse_when_disabled 不知道「false」對應什麼業務語義（feature 關掉？user 不存在？status 失效？）——把業務語義寫進名字、讀者一眼就能 map 到實際情境。

反模式 5：用 numbering 取代命名

正向概念：每個 test case 都有獨特的「驗什麼情境」、命名就是把那個情境寫出來。編號只負責「不重複」、不負責「能識別」——失去命名最關鍵的功能。

1// 反：靠編號區分
2test('addItem_case_1', () { ... });
3test('addItem_case_2', () { ... });
4test('addItem_case_3', () { ... });
5
6// 正：編號變描述
7test('addItem_appends_when_cart_empty', () { ... });
8test('addItem_increments_when_same_item_exists', () { ... });
9test('addItem_handles_null_customization', () { ... });

編號是「我懶得想名字」的訊號。讀者要跳進 test body 才能區分 case 1 跟 case 2 是什麼差別——失去測試命名的全部 doc 價值；CI 報告看到「addItem_case_2 失敗」也無從直接判斷哪個情境壞了。

邊界：什麼時候測試名不適合當 spec

「測試名是 spec 條目」是預設、但有些情境測試命名無法獨自承擔 doc 責任：

• 大量參數化 / property-based test：「對任意輸入 N、結果都 ≥ N」這類 invariant、命名只能寫概念名（preserves_minimum）、具體 input 範圍要靠 doc 或 generator 描述
• 整合 / e2e test：跨多個系統的行為、命名常壓不下完整流程（「user_can_complete_checkout_with_loyalty_points_and_split_payment」）、要靠 setup / scenario doc 補上下文
• 測試本身是業務動機的二次表達：例如 GDPR 合規規則、業務動機的詳細條款仍要寫在介面 doc / spec 文件、命名只負責「驗證點」
• 內部行為對齊 vs 對外契約：私有 helper / internal worker 的測試命名不必當公開 spec、可以直接用實作詞彙（這時候命名價值是「regression 防護」而非「對外文件」）

判斷標準：「讀者只看名字、能不能拿到他要的資訊？」答「能」就讓命名當 spec 用、答「不能」就把詳細上下文寫進 doc / scenario file、命名只當「定位錨點」。

給測試寫作的 checklist

寫一個 test 之前，跑這個 checklist：

• 名字能不能讓讀者不看 body 就知道驗證什麼？ 不能 → 重命名
• 名字描述的是被測 function 的契約嗎？ 不是（描述測試過程）→ 重寫
• 名字有沒有業務面詞彙？ 沒有（只有 assertion 動詞）→ 加業務詞彙
• 同 group 下這個名字跟其他 test 有區辨度嗎？ 沒有（靠編號）→ 加情境描述
• 這個行為契約是 doc 沒寫但這個 test 在驗的嗎？ 是 → 太好了，這個 test 補了 doc 漏洞
• 這個 test 在驗實作細節嗎？ 是 → 改成驗對外可觀察行為，否則重構必折斷

Trade-off：測試名變長的代價

把測試當 doc 寫，名字會變長——addItem_increments_quantity_when_same_item_exists_with_identical_customizations 比 test_add 長 5 倍。

值得嗎？看你怎麼讀測試：

• 只看綠紅燈、不讀名字 → 短名字便利
• 把測試當 spec 讀 → 長名字回收成本

多數團隊低估「把測試當 spec 讀」的價值，因為這個習慣需要團隊一致才有效——一個人寫好命名，其他人不讀，回收不到。這是團隊習慣問題，不是個人偏好問題。要建立這個習慣，最好的切入點是：

1. 新功能 PR 直接讀新 test 的名字判斷契約是否合理——把命名變成 review 的一環
2. 修 bug 時要求新增的 regression test 名字描述 bug 行為（例如 does_not_double_charge_on_retry）——這些名字本身是 incident 紀錄
3. 重構 PR 不允許改 test 名（除非是改名抓 bug 暴露的契約變動）——避免重構順手「整理」掉重要命名

一句話 heuristic

把整個討論濃縮：

測試名是「讀者跳到測試檔、不看 body 就能讀懂的 spec 條目」。

寫測試名時想像一個讀者只會看到名字，他要能從名字推得：

• 在驗哪個操作？
• 在哪個情境下？
• 期待什麼結果？

三件事缺一不可。寫到名字過長覺得難寫——通常是被測 function 同時在做多件事，測試名長是設計訊號，先別急著縮名字，先想能不能拆 function。

收束：測試命名是文件設計的一環

回到開頭——測試是少數會自我驗證的文件。但這個性質只在你有意識利用時才有價值。把測試名寫成 test_1、test_2，你寫的是 regression 網，不是 doc。

把測試名寫成可讀 spec 條目，你寫的是同時包辦兩件事的東西：驗證 + 文件。這兩件事用同一份成本同時做完，是測試這個工具的最高槓桿用法。

把「這份 test file 是這個模組唯一的 doc、讀者夠不夠用？」當成命名的品質門檻——通過這個門檻的命名、自然就具備可讀 spec 的特性。