單行註釋
- 使用
// 風格，前方必須有一空行**
- 與後續代碼保持**相同縮進層級**
- 註釋內容首字母大寫，以句號結尾
- 解釋「為什麼」而非「做什麼」
<?php
// 計算訂單總價含稅金額
$total = $subtotal * (1 + $taxRate);
// 驗證用戶權限：僅管理員可訪問審計日誌
if ($user->hasRole('admin')) {
// ...
}
行尾註釋
- 用於**極短**說明，與代碼同行，前方**至少一空格**
- 多行連續行尾註釋應**對齊列位置** (通常列 80 或 120)
- 不超過行長度硬限制 (180 字符)
<?php
const MAX_RETRIES = 3; // 最大重試次數
const TIMEOUT_MS = 5000; // 請求超時毫秒數
const DEFAULT_LOCALE = 'zh_TW'; // 系統預設語言
if ($status === 200) { // 請求成功
return $response->json();
}
塊註釋 (DocBlock) 與單行註釋選擇
| 場景 | 推薦風格 | 示例 |
|---|
| 類/介面/方法/屬性/常量 | DocBlock /** ... */ | 見規範 (三) |
| 函數/方法內部邏輯分段 | 單行 // | // 驗證輸入參數 |
| 臨時禁用代碼塊 | 行尾 // 逐行 | // $debug = true; |
| 複雜演算法步驟說明 | 塊註釋 /* ... */ | 見下文 |
| TODO/FIXME/XXX 標記 | 單行 // TODO: ... | // TODO: 引入緩存層優化查詢 |
塊註釋規範 (非 DocBlock)
- 用於**多行邏輯解釋**，不可嵌套
- 起始
/* 獨佔一行，結束 */ 獨佔一行
- 內容每行以
* 開頭，對齊
<?php
/*
* 此處採用樂觀鎖機制防止併發更新衝突：
* 1. 讀取實體時獲取 version 字段
* 2. 更新時 WHERE id = ? AND version = ?
* 3. 受影響行數為 0 則拋出 ConcurrentModificationException
*/
$updated = $entityManager->updateWithVersion($entity);
註釋內容質量要求
- 保持同步：代碼變更時必須同步更新註釋
- 避免顯而易見：
// 循環數組 ❌ → // 過濾已過期的優惠券 ✅
- 業務語境：說明業務規則來源（如「根據財務規範 FD-2023-005 計算利息」）
- 引用鏈接：
// @see https://jira.example.com/browse/PROJ-1234
自動化檢查
- PHP_CodeSniffer
Squiz.Commenting.PostStatementComment、PSR12.Commenting.SingleLineComment
- PHPStan
phpdoc 規則檢查 DocBlock 完整性
- IDE 檢查：PhpStorm
Inspections → PHP → Commenting
