程式碼註解內容界線
註解寫「為什麼這樣寫」，不寫「這件事記在哪份文件」。文件編號會過期、會搬家、會在存取權限外，讀程式碼的人查不到，只留下一串無意義的代號。
code-review 第 2 組（可讀性）依本清單審查；jsc-hooks 的 comment-scope.sh 在寫檔後自動比對並發出警告。
有兩項樣式判定不了：專案代號、客戶名稱。hook 抓不到這兩項，只能靠 code-review 人工判讀。hook 只掃這次新增的註解行，不翻既有程式碼的舊帳。
適用範圍
| 對象 |
是否受限 |
程式碼註解（//、#、/* */、--、<!-- --> 等） |
受限 |
docstring、API 文件註解（含 @param、@return 內容） |
不受限 |
| README、設計文件、其他 markdown |
不受限 |
| commit 訊息、PR 描述 |
不受限 |
禁止寫進註解
追蹤系統編號
| 項目 |
命中例 |
| 議題編號 |
// #123、// ABC-123 |
| PR 編號、MR 編號 |
// 見 PR !45 |
| 變更單編號、CR 編號 |
// CR-2026-07 |
| 議題留言引用 |
// 見 #123 第三則留言 |
jsc wiki 頁面編號
| 項目 |
命中例 |
| 規劃頁編號與分頁編號 |
// PLAN_A1B2C3D4 第 2 頁 |
| 分析頁編號 |
// ANALYZE_A1B2C3D4 |
| 工作包編號 |
// WP-01 |
| TDD 待辦編號 |
// todo 3 |
| 交付頁編號 |
// DELIVER_A1B2C3D4 |
| 維運頁編號 |
// MAINTAIN_A1B2C3D4 |
| 異常頁編號 |
// ERROR_A1B2C3D4 |
| 問詢頁編號 |
// QUESTION_A1B2C3D4 |
| 工作日誌頁編號 |
// LOG_A1B2C3D4 |
| 教訓頁編號 |
// LEARN_A1B2C3D4 |
| 盤點頁編號 |
// REPO_A1B2C3D4 |
| wiki 頁面網址 |
// https://gitea.example/…/wiki/PLAN_A1B2C3D4 |
需求與規格編號
| 項目 |
命中例 |
| 使用者故事編號 |
// US-01 |
| 驗收條件編號 |
// AC-01 |
| 測試案例編號 |
// TC-01 |
| 規格文件章節編號 |
// 規格書 3.2.1 節 |
| 稽核檢查項編號 |
// guidelines 第 7 項 |
流程與人事資訊
| 項目 |
命中例 |
| 分支名稱、commit hash |
// 見 commit a1b2c3d |
| 版本號、里程碑、Sprint 編號 |
// Sprint 12 加入 |
人名、認領者、@ 提及、@author |
// @someone 認領 |
| 工時估算、CPM 數據 |
// 預估 3 小時 |
| 專案代號、客戶名稱 |
// 客戶 XX 專案 |
| 產生來源署名、AI 署名 |
// 本檔由 jsc-sdlc:implement 產生 |
| 外部文件連結 |
// 見 Confluence、Notion、Google Docs 連結 |
審查流程痕跡
這些資訊是討論當下的座標。沒有參與那場討論的人看不懂，討論結束後也會失效。註解要留下程式邏輯的原因，不留下審查流程的路徑。
| 項目 |
命中例 |
review、code review 字樣用來描述審查流程 |
// code review 要求改成共用函式 |
| 輪次描述 |
// 第二輪追加檢查這個分支 |
| 問題與發現編號 |
// Finding1：避免空指標、// 問題3 已修 |
| 審查者代稱或工具名 |
// hermes 建議保留這個判斷、// CodeReview bot 標出這裡 |
| 審查狀態標籤 |
// 真缺陷，已解決、// BLOCKING |
允許寫進註解
| 項目 |
允許的理由 |
例 |
| 日期與時間戳 |
標示某個決定的時間點，不依賴外部系統 |
// 2026-08-26 起改用新費率 |
| 需求變更歷程 |
說明「為什麼不是更直覺的那個做法」 |
// 原本四捨五入，改成無條件捨去 |
| RFC、ISO 等標準規格編號與章節 |
指向公開且長期穩定的規格 |
// 依 RFC 7231 第 6.5.1 節 |
| CVE 編號 |
說明這段防護在擋什麼 |
// 修補 CVE-2026-1234 |
| 第三方套件的 issue 連結 |
說明繞道寫法的成因與解除條件 |
// 繞過 github.com/foo/bar/issues/88，修好後可移除 |
| 授權標頭、SPDX 標記 |
法律要求 |
// SPDX-License-Identifier: MIT |
| 語言原生標記 |
編譯器或工具鏈直接解讀 |
@deprecated、@since |
@author 不在允許之列：它是人名，屬「流程與人事資訊」。
命中時怎麼改
| 原本 |
改成 |
// WP-03 要求這裡回傳空陣列 |
// 查無資料回傳空陣列，呼叫端不必再判 null |
// 見 #123 |
把 #123 裡的原因寫進註解本身 |
// @someone 2026-08-26 修 |
// 2026-08-26 改用新費率 |
// PLAN_A1B2C3D4 第 2 頁的規則 |
把該頁的規則正文濃縮成一句寫進來 |
// Finding1：避免空指標 |
// 輸入來自外部系統，空值要直接略過 |
// 第二輪追加這個判斷 |
// 舊資料可能缺欄位，先補預設值再解析 |
原則一句話：把編號指向的內容搬進註解，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。
