awoooi/docs/adr/ADR-013-code-annotation-standards.md

ADR-013: Code Annotation Standards

狀態: 🟡 草稿 (待 CTO 批准) 日期: 2026-03-24 決策者: CTO

背景

AWOOOI 專案缺乏統一的代碼註解規範，導致：

• Code Review 時對「是否需要註解」有爭論
• 新人入職時難以理解複雜邏輯
• 危險操作缺乏警示說明

決策

採用分層註解策略，區分「強制」與「建議」場景。

---

1. 強制註解場景 (Must Have)

以下場景必須有註解，否則 PR 不予合併：

1.1 安全相關

# 🔐 Token 驗證: 檢查 JWT 是否過期且具有對應 Tier 權限
def verify_token(token: str, required_tier: int) -> bool:

1.2 複雜邏輯

// 正則說明: 匹配 K8s Pod 名稱格式 <deployment>-<hash>-<random>
const POD_NAME_REGEX = /^(.+)-([a-f0-9]{8,10})-([a-z0-9]{5})$/

1.3 外部依賴

# 🌐 外部 API: Alertmanager webhook，預期回應 200 OK
async def send_to_alertmanager(payload: dict) -> bool:

1.4 危險操作

# 🔴 危險: 此 NetworkPolicy 控制 Worker 出站流量
# 修改前請確認 Redis/PostgreSQL 連線不受影響
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy

---

2. 格式規範

2.1 Python (Google Style Docstring)

def restart_pod(namespace: str, pod_name: str) -> bool:
    """重啟指定 Pod。

    Args:
        namespace: K8s 命名空間
        pod_name: Pod 名稱 (不含 hash 後綴)

    Returns:
        True 表示重啟成功

    Raises:
        K8sPermissionError: 缺少 delete pods 權限

    Warning:
        此操作會導致短暫服務中斷
    """

2.2 TypeScript (JSDoc)

/**
 * 簽核待審批請求
 * @param id - Approval UUID
 * @param signerId - 簽核者 ID (需有對應 Tier 權限)
 * @returns 簽核結果，包含是否觸發執行
 * @throws {UnauthorizedError} 簽核者權限不足
 * @example
 * const result = await signApproval('abc-123', 'admin-001')
 * if (result.execution_triggered) { ... }
 */
async function signApproval(id: string, signerId: string): Promise<ApprovalResult>

2.3 YAML/Kubernetes

# 🔴 危險操作標記
# 📝 用途說明
# ⚠️ 注意事項

---

3. 測試標記 (data-testid)

命名規則

<component>-<element>[-<action>]

範例

<button data-testid="approval-card-approve-btn">
<input data-testid="search-input-filter">
<div data-testid="incident-list-container">

強制場景

• 所有可交互元素 (button, input, select)
• E2E 測試會定位的容器
• 動態渲染的列表項

---

4. 不需要註解的場景

• 自明的 CRUD 操作
• 標準庫/框架常見用法
• 已有 TypeScript 型別說明的參數

---

5. 執行方式

Phase 1 (本週)

• ADR-013 文件建立
• ESLint require-jsdoc 配置 (危險函數)
• Ruff D100 規則 (公開函數)

Phase 2 (下週)

• 補齊 P0/P1 關鍵模組註解
• 補齊 data-testid (Approval/Incident)
• CI 加入 lint 檢查

Phase 3 (持續)

• Code Review 強制執行
• 新代碼必須符合標準

---

6. 參考

• Google Python Style Guide
• JSDoc Reference
• Testing Library - data-testid