Merge pull request 'feat/comment-scope-rule' (#8) from feat/comment-scope-rule into develop

Reviewed-on: #8
2026-08-27 00:56:41 +00:00
parent 1990476b25 0df99db512
commit 8b8f23a17b
7 changed files with 106 additions and 6 deletions
@@ -1,6 +1,6 @@
 {
  "name": "jsc-review",
-  "version": "0.0.4",
+  "version": "0.0.5",
  "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
  "skills": "./skills",
  "author": {
@@ -1,6 +1,6 @@
 {
  "name": "jsc-review",
-  "version": "0.0.4",
+  "version": "0.0.5",
  "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
  "skills": "./skills"
 }
@@ -26,7 +26,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安

 ### `code-review`

-對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。
+對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。

 <!-- JSC-SKILLS:END -->

@@ -35,6 +35,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | 檔案 | 用途 |
 | --- | --- |
 | `references/smells.md` | 六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 |
+| `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號清單、允許項目與白名單、命中時的改法 |

 ## 相關 domain

@@ -1,6 +1,6 @@
 {
  "name": "jsc-review",
-  "version": "0.0.4",
+  "version": "0.0.5",
  "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
  "skills": "./skills/"
 }
@@ -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 頁的規則` | 把該頁的規則正文濃縮成一句寫進來 |
+
+原則一句話：把編號指向的內容**搬進註解**，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。
@@ -57,6 +57,13 @@
 - **建議重構手法**：Extract Function（用函式名取代註解）、Rename（用命名取代註解）、Introduce Assertion；保留「為什麼」與外部限制類註解。
 - **注意**：本項與「註解問題」（第 5 組）互補：刪除解釋性廢話註解，補齊第 5 組要求的介面契約註解，兩者不衝突。

+### 2.5 文件編號夾帶（Document Reference Leak）
+
+- **定義**：註解寫的是「這件事記在哪份文件」，不是「為什麼這樣寫」。編號會過期、會搬家、會在存取權限外，讀程式碼的人查不到，只剩一串無意義的代號。
+- **偵測訊號**：註解含議題編號（`// #123`、`// ABC-123`）、wiki 頁編號（`// PLAN_A1B2C3D4`）、工作包編號（`// WP-01`）、commit hash（`// 見 commit a1b2c3d`）、`@` 提及（`// @someone 認領`）、外部文件連結（Confluence、Notion、Google Docs）。完整禁止清單、允許清單與適用範圍看 `references/comment-scope.md`。
+- **建議重構手法**：把編號指向的內容搬進註解，再刪掉編號；搬不動就代表那件事不該用註解表達，改寫進文件。
+- **注意**：本項與 2.4、第 5 組分工明確：2.4 刪解釋性廢話，第 5 組補介面契約，2.5 刪文件編號。
+
 ## 第 3 組：耦合與設計問題（Couplers）

 ### 3.1 依賴嫉妒（Feature Envy）
@@ -155,4 +162,4 @@
 | --- | --- | --- |
 | 高 | 會造成錯誤或已阻礙修改 | 吞掉異常、重複程式碼改漏、死碼誤導 |
 | 中 | 持續增加維護成本 | 巨型類別、臃腫函式、巢狀地獄、Couplers 全組 |
-| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、淺模組 |
+| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、文件編號夾帶、淺模組 |
@@ -25,7 +25,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
   | Group | Scope |
   | --- | --- |
   | 1 Bloaters | smells.md group 1 |
-   | 2 Obscurity | smells.md group 2 |
+   | 2 Obscurity | smells.md group 2, including 2.5 document reference leak — comments carrying issue ids, wiki page ids, work package ids, commit hashes, @ mentions, or external document links; the full banned and allowed lists live in `references/comment-scope.md` |
   | 3 Couplers | smells.md group 3 |
   | 4 Dispensables & Others | smells.md group 4 |
   | 5 Comment contract | smells.md group 5 |
@@ -39,5 +39,6 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)

 ## Notes

+- `jsc-hooks`' `comment-scope.sh` already matches the pattern-detectable items after every file write. Group 2 here covers what patterns cannot decide — project code names and customer names — plus the overall judgment; the two never report the same finding twice.
 - If group 5 examples are fetched from a database, they must be de-identified; never include personal data.
 - When there are no findings, report the literal 「無發現」 explicitly; never leave the report empty.