| 類型 | 用途 | 格式 | 適用場景 |
|---|---|---|---|
| 區塊註解 | 說明程式區塊邏輯、演算法、複雜流程 | /* ... */ | 函數/類別前、複雜邏輯區段 |
| 單行註解 | 簡短說明單行或少數行程式碼 | // ... | 變數宣告旁、簡單邏輯說明 |
| 行尾註解 | 同行程式碼後說明 | code; // ... | 參數含義、魔術數字解釋 |
| 尾端註解 | 程式碼區塊結束後說明 | } // 結束 if | 長區塊結束標示 |
| 文件註解 | API 文件產生、IDE 智慧提示 | /** ... */ (PHPDoc) | 檔案頭、類別、方法、屬性、常數 |
/* 開頭,*/ 結尾,每行以 * 開頭對齊。/*- 開頭防止 indent 重排。<?php
/*
* 計算訂單總價:
* 1. 累加商品小計
* 2. 套用優惠券折扣
* 3. 加上運費
*/
$total = calculateSubtotal($items);
$total = applyCoupon($total, $coupon);
$total += calculateShipping($address);
?>
<?php
if ($condition) {
// 處理符合條件的訂單
processOrder($order);
}
?>
//。// 位置。<?php
$taxRate = 0.05; // 稅率 5%
$maxRetry = 3; // 最大重試次數
?>
<?php
if ($user->isActive()) {
// ... 幾十行邏輯 ...
} // 結束 if ($user->isActive())
?>
遵循 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],
];
}
?>
| 標籤 | 用途 | 範例 |
|---|---|---|
@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) |
@dataProvider。$i++; // i 加 1)。phpcs (PHP_CodeSniffer) + phpdoc 標準強制檢查。良好的註解習慣是專案長期可維護的基石,PHPDoc 更是現代 PHP 開發的標準語言。