2026-08-27 00:56:41 +00:00
2 changed files with 99 additions and 1 deletions
@@ -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 全組 |
-| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、淺模組 |
+| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、文件編號夾帶、淺模組 |