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 組可讀性審查。
This commit is contained in:
@@ -0,0 +1,91 @@
|
||||
# 程式碼註解內容界線
|
||||
|
||||
註解寫「為什麼這樣寫」，不寫「這件事記在哪份文件」。文件編號會過期、會搬家、會在存取權限外，讀程式碼的人查不到，只留下一串無意義的代號。
|
||||
|
||||
`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 頁的規則` | 把該頁的規則正文濃縮成一句寫進來 |
|
||||
|
||||
原則一句話：把編號指向的內容**搬進註解**，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。
|
||||
Reference in New Issue
Block a user