萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 編碼規範:文件註解五大類型與最佳實踐

註解類型總覽

類型用途格式適用場景
區塊註解說明程式區塊邏輯、演算法、複雜流程/* ... */函數/類別前、複雜邏輯區段
單行註解簡短說明單行或少數行程式碼// ...變數宣告旁、簡單邏輯說明
行尾註解同行程式碼後說明code; // ...參數含義、魔術數字解釋
尾端註解程式碼區塊結束後說明} // 結束 if長區塊結束標示
文件註解API 文件產生、IDE 智慧提示/** ... */ (PHPDoc)檔案頭、類別、方法、屬性、常數

各類型詳細規範

1. 區塊註解

  • 以 /* 開頭,*/ 結尾,每行以 * 開頭對齊。
  • 前方應有一空行分隔。
  • 可用 /*- 開頭防止 indent 重排。
<?php
/* 
 * 計算訂單總價:
 * 1. 累加商品小計
 * 2. 套用優惠券折扣
 * 3. 加上運費
 */
$total = calculateSubtotal($items);
$total = applyCoupon($total, $coupon);
$total += calculateShipping($address);
?>

2. 單行註解

  • 前方保留一空行。
  • 縮進與後續程式碼一致。
<?php
if ($condition) {
    // 處理符合條件的訂單
    processOrder($order);
}
?>

3. 行尾註解

  • 程式碼結束後至少一空格再加 //。
  • 多行行尾註解對齊 // 位置。
  • 不宜過長,超過 80 字元改用區塊註解。
<?php
$taxRate = 0.05;  // 稅率 5%
$maxRetry = 3;    // 最大重試次數
?>

4. 尾端註解

  • 用於長區塊(if/for/while/function)結尾,標示結束對應關係。
<?php
if ($user->isActive()) {
    // ... 幾十行邏輯 ...
} // 結束 if ($user->isActive())
?>

5. 文件註解 - 核心重點

遵循 PHPDoc 標準,支援 IDE 自動完成、靜態分析、文件產生器。

檔案頭註解

<?php
/**
 * 訂單處理服務
 *
 * @package    App\Services
 * @author     Jane Doe 
 * @version    2.1.0
 * @license    MIT
 */
?>

類別註解

<?php
/**
 * 訂單服務類別
 *
 * 提供訂單建立、查詢、狀態變更功能
 *
 * @property-read int $totalOrders 總訂單數
 * @method     Order create(array $data) 建立訂單
 */
class OrderService {
    // ...
}
?>

方法/函數註解

<?php
/**
 * 計算訂單總金額
 *
 * @param  array  $items    商品列表 [['price'=>100, 'qty'=>2], ...]
 * @param  Coupon|null $coupon 優惠券物件
 * @return float 總金額
 * @throws InsufficientStockException 庫存不足
 * @throws InvalidCouponException 優惠券無效
 */
public function calculateTotal(array $items, ?Coupon $coupon = null): float {
    // ...
}
?>

屬性/常數註解

<?php
class Order {
    /** @var int 訂單狀態:0=待付款, 1=已付款, 2=已出貨, 3=已完成, -1=取消 */
    public int $status = 0;

    /** @var string[] 允許的狀態轉換規則 */
    protected array $transitions = [
        0 => [1, -1],
        1 => [2, -1],
    ];
}
?>

常用 PHPDoc 標籤速查

標籤用途範例
@param參數型別、名稱、說明@param string $name 使用者名稱
@return回傳型別、說明@return User|null 使用者物件或 null
@throws可能拋出的例外@throws \Exception 發生錯誤時
@var屬性/變數型別@var int $id
@property魔術屬性@property string $fullName
@method魔術方法@method static User find(int $id)
@deprecated標記棄用@deprecated 使用 newMethod() 代替
@see參考連結@see https://example.com/docs
@SuppressWarnings靜態分析忽略@SuppressWarnings(PHPMD.UnusedVariable)

工具鏈整合

  • IDE:PhpStorm、VS Code (PHP Intelephense) 自動讀取 PHPDoc 提供型別提示、跳轉定義。
  • 靜態分析:PHPStan、Psalm 依據 PHPDoc 推導型別,發現潛在錯誤。
  • 文件產生:phpDocumentor、ApiGen 產生 HTML API 文件。
  • 測試:PHPUnit 資料提供者可參考 @dataProvider。

團隊規範建議

  1. 所有公開 API(public/protected 方法、介面)強制撰寫 PHPDoc。
  2. 私有方法視複雜度決定,建議至少單行說明用途。
  3. 避免無意義註解(如 $i++; // i 加 1)。
  4. 註解與程式碼同步維護,過期註解比無註解更有害。
  5. 引入 phpcs (PHP_CodeSniffer) + phpdoc 標準強制檢查。

良好的註解習慣是專案長期可維護的基石,PHPDoc 更是現代 PHP 開發的標準語言。

copyright © 萬盛學電腦網 all rights reserved