良好的註釋是代碼文檔化的基石。PHP 支持三種註釋風格,配合 DocBlock 標準與現代靜態分析工具,能實現代碼自文檔化、類型提示補全、自動生成 API 文檔。
| 風格 | 語法 | 適用場景 | 巢狀支持 |
|---|---|---|---|
| C++ 風格 | // 單行註釋 | 行內說明、臨時註釋 | ❌ |
| C 風格 | /* 多行註釋 */ | 大段代碼暫時禁用、文件頭版權 | ❌ (遇首個 */ 結束) |
| Shell 風格 | # 單行註釋 | 配置文件、CLI 腳本 | ❌ |
<?php
/**
* 計算矩形面積
*
* @param float $width 寬度
* @param float $height 高度
* @return float 面積
* @throws InvalidArgumentException 參數為負數
* @see Rectangle::perimeter()
* @since 1.2.0
* @deprecated 使用 Rectangle::area() 實例方法
*/
function calcArea(float $width, float $height): float {
if ($width < 0 || $height < 0) {
throw new InvalidArgumentException('尺寸不能為負');
}
return $width * $height;
}
@param type $name 描述:參數(類型支持聯合 int|float、可空 ?string)。@return type 描述:返回值。@var type:屬性/變量類型提示(IDE 推斷輔助)。@throws ExceptionClass 描述:拋出異常。@see:關聯參考。@deprecated:棄用提示。@psalm-*/@phpstan-*:靜態分析專用元數據。#[Attribute] 逐步替代部分 DocBlock 元數據(如路由、驗證、ORM 映射)。// ❌ 無意義註釋
$i++; // i 加 1
// ❌ 過時註釋
// 連接 MySQL
$pdo = new Pgsql(...); // 實際連 PostgreSQL
// ❌ 註釋掉代碼留存(用版本控制替代)
/* $oldCode = ... */
註釋解釋「為什麼」,代碼表達「做什麼」。遵循 DocBlock 標準、配合靜態分析工具、及時維護同步,讓註釋成為提升團隊效率的資產而非負債。