Files

T

jiantw83 fd70ce3bc2 feat(review): 新增程式碼註解禁止夾帶文件資訊的規則正文

What：新增 references/comment-scope.md 規則正文，並在 references/smells.md
第 2 組加入 2.5 文件編號夾帶，嚴重度分級「低」列補上本項。

Why：註解寫「這件事記在哪份文件」，讀程式碼的人查不到。編號會過期、會搬家、
會落在存取權限外，最後只剩一串無意義的代號。註解該寫的是「為什麼這樣寫」。

How：規則正文限定適用範圍只到程式碼註解，docstring、README、commit 訊息不受限。
禁止清單三十項分四組：追蹤系統編號、jsc wiki 頁面編號、需求與規格編號、
流程與人事資訊。白名單七項：日期與時間戳、需求變更歷程、RFC 與 ISO 標準、CVE、
第三方套件 issue 連結、授權標頭與 SPDX、語言原生標記。

Who：jsc-review 的 code-review 技能，第 2 組可讀性審查。

2026-08-26 19:00:38 +08:00

3.9 KiB

Raw Blame History

程式碼註解內容界線

註解寫「為什麼這樣寫」，不寫「這件事記在哪份文件」。文件編號會過期、會搬家、會在存取權限外，讀程式碼的人查不到，只留下一串無意義的代號。

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 連結`

允許寫進註解

項目	允許的理由	例
日期與時間戳	標示某個決定的時間點，不依賴外部系統	`// 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 頁的規則`	把該頁的規則正文濃縮成一句寫進來

原則一句話：把編號指向的內容搬進註解，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。

3.9 KiB Raw Blame History