六個方法

init

SDK 初始化。設定 collector endpoint、app 識別資訊、flush 間隔、buffer 大小。在 app 啟動時呼叫一次。

1Monitor.init({
2  endpoint: 'https://collector.example.com/v1/events',
3  app: 'my_app',
4  version: '1.2.0',
5  flushInterval: 30000,   // 毫秒
6  bufferSize: 100,
7})

init 負責建立 session、記錄 lifecycle.session.start 事件、啟動 flush 計時器。init 之前呼叫其他方法應該拋出明確錯誤（SDK 未初始化），而非靜默忽略。

連線驗證策略：lazy。init 不驗證 collector 是否可達 — 不發 HTTP 請求、不 ping endpoint。init 的失敗只代表配置錯誤（缺少 endpoint 參數），不代表網路問題。網路問題在第一次 flush 時才浮現，flush 失敗時事件保留在 buffer 等待重試。

Lazy 策略的理由：SDK 不應阻塞主程式的啟動流程。如果 init 驗證連線，collector 暫時不可用時 app 會啟動失敗 — 監控工具反而變成可用性的瓶頸。短生命週期腳本（Python 平台適配：短生命週期腳本）對這一點更敏感 — hook 腳本不能因為 collector 沒啟動就拒絕執行。

event

記錄使用者操作事件（四類事件中的 Event 類）。接受事件名稱和可選的 data 物件。

1Monitor.event('terminal.connect.start', { url: 'wss://...' })
2Monitor.event('enrollment.qr.scan')

event 方法是非阻塞的 — 事件進入內部 buffer 立即返回，不等待網路送出。應用程式的操作流程不應該被監控 SDK 的網路延遲阻塞。

error

記錄錯誤事件。接受 Error/Exception 物件或自訂的錯誤描述。自動附加 stack trace、錯誤類型、觸發位置。

1Monitor.error(exception, { step: 'ws_connect' })
2Monitor.error('Auth token missing', { context: 'handshake' })

error 方法和自動攔截機制（自動攔截）互補 — 自動攔截處理未捕獲的例外，error 方法處理開發者主動上報的已知錯誤。

metric

記錄數值指標。接受指標名稱和數值。

1Monitor.metric('connect.duration_ms', 320)
2Monitor.metric('terminal.fps', 58.5)

metric 方法記錄的是離散的數值快照。聚合計算（平均、百分位、趨勢）在 collector 端完成，SDK 端只負責記錄原始值。

flush

強制送出 buffer 中所有待發事件。正常情況下 SDK 按 flushInterval 定期自動 flush（攢批送出）。flush 方法用於需要確保事件已送出的場景 — 例如 app 即將進入背景或使用者手動觸發 log 上傳。

1await Monitor.flush()

flush 是非同步方法 — 需要等待網路請求完成。呼叫端可以 await 確認送出成功，也可以 fire-and-forget。

close

SDK 資源釋放。停止 flush 計時器、送出 buffer 中剩餘事件、關閉網路連線、記錄 lifecycle.session.end 事件。

1await Monitor.close()

close 在 app 關閉時呼叫。呼叫後 SDK 進入已關閉狀態，後續的 event/error/metric 呼叫應該被靜默忽略（不拋錯，因為 app 正在關閉）。

API 設計原則

方法名稱和四類事件對齊。event / error / metric 三個方法直接對應三類事件，lifecycle 事件由 init 和 close 自動產生。開發者看到方法名稱就知道對應哪類事件。

所有上報方法非阻塞。event、error、metric 進 buffer 立即返回。監控 SDK 阻塞應用程式的操作流程是反模式。

init 和 close 成對出現。init 開始 session，close 結束 session。兩者界定 SDK 的活躍期間。

各平台的 SDK 整合範例（Flutter 的 pubspec.yaml + main.dart init、Python 的 pip install + init code、JS 的 script tag + init）見 monitor repo 各 SDK 的 README。

下一步路由

• 自動攔截未捕獲的錯誤 → 自動攔截機制
• Buffer 和 flush 的策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• SDK 的 HTTP POST 行為需要 protocol test → testing 模組三 協議整合測試

核心命題：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 的合法輸入範圍」這個訊號時、自問：「這三行能不能變成型別簽章？」——多半可以。