把「請不要這樣做」的註解變成 lint 規則
讓工具記住規矩,讓人專心做判斷。
註解只在剛好被讀到時有用
我們都看過這種註解:「這裡不要直接用 fetch」「這個元件不要在 client 用」「改這裡要記得改那裡」。它們是寫給人看的提醒,新人不一定讀到,趕時間的時候也不一定讀到。
註解
是願望。違反了沒人知道,要等 review 或出事才發現。
lint 規則
是規則。存檔或 CI 當下就知道,錯誤訊息直接說錯在哪、為什麼。
不管 code 是人寫的還是工具產生的,lint 都在寫的當下回饋;review 的人少記一條要提醒的事,注意力留給真正需要判斷的地方。
三個例子
格式都一樣:原本的註解 → 對應的規則 → 把註解裡的理由搬進 message。
1. 「不要直接用 fetch,請用 apiClient」
// eslint.config.js
rules: {
'no-restricted-globals': ['error', {
name: 'fetch',
message: '請用 apiClient,統一處理 token 和錯誤。',
}],
}
2. 「不要整包 import lodash」
rules: {
'no-restricted-imports': ['error', {
paths: [{
name: 'lodash',
message: '請用 lodash/xxx 單獨 import,避免整包打進來。',
}],
}],
}
3. 「這個模組只能在 server 用」
// server 專用的檔案最上面加一行
import 'server-only'
Next.js 的做法:client 端一 import 就在 build 時報錯,比註解可靠。
重點:message 寫的是「為什麼」,不是只寫「不准」。看到錯誤的人就知道理由,不用去問。
怎麼開始
- 搜 code 裡的「不要」「請勿」「記得」「DO NOT」,挑一條最常被踩的。
- 先設
warn,不擋 build,觀察一兩週會跳幾個地方。 - 清乾淨再改成
error。 - 一次一條。需要看情況判斷的,就留在註解。
帶回去的問題:我們 code 裡有沒有哪一句「請不要這樣做」,是你被踩過、或 review 時重複提醒過的?
延伸
- 規則更細的寫法:ESLint 的
no-restricted-syntax用選擇器擋特定寫法,不用自己寫 plugin。 - 能用 TypeScript 型別擋的,比 lint 更早擋住。