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:
2026-08-26 19:00:38 +08:00
parent 1990476b25
commit fd70ce3bc2
2 changed files with 99 additions and 1 deletions
+8 -1
View File
@@ -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 全組 |
| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、淺模組 |
| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、文件編號夾帶、淺模組 |