把「請不要這樣做」的註解變成 lint 規則

十分鐘分享 · 2026-11

讓工具記住規矩,讓人專心做判斷。

註解只在剛好被讀到時有用

我們都看過這種註解:「這裡不要直接用 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 寫的是「為什麼」,不是只寫「不准」。看到錯誤的人就知道理由,不用去問。

怎麼開始

  1. 搜 code 裡的「不要」「請勿」「記得」「DO NOT」,挑一條最常被踩的。
  2. 先設 warn,不擋 build,觀察一兩週會跳幾個地方。
  3. 清乾淨再改成 error。
  4. 一次一條。需要看情況判斷的,就留在註解。
帶回去的問題:我們 code 裡有沒有哪一句「請不要這樣做」,是你被踩過、或 review 時重複提醒過的?

延伸