萬盛學電腦網

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

PHP 註釋規範完全指南:三種風格、單行多行、DocBlock 與工具鏈

良好的註釋是代碼文檔化的基石。PHP 支持三種註釋風格,配合 DocBlock 標準與現代靜態分析工具,能實現代碼自文檔化、類型提示補全、自動生成 API 文檔。

三種註釋風格

風格語法適用場景巢狀支持
C++ 風格// 單行註釋行內說明、臨時註釋❌
C 風格/* 多行註釋 */大段代碼暫時禁用、文件頭版權❌ (遇首個 */ 結束)
Shell 風格# 單行註釋配置文件、CLI 腳本❌

DocBlock 文檔註釋標準 (PHPDoc/PSR-5)

<?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-*:靜態分析專用元數據。

現代工具鏈整合

  • IDE 支持:PhpStorm/VS Code (PHP Intelephense) 讀取 DocBlock 提供類型提示、跳轉、重構。
  • 靜態分析:Psalm、PHPStan、Rector 利用 DocBlock 補全類型系統缺口(PHP 7.4 前無屬性類型聲明時尤關鍵)。
  • 文檔生成:phpDocumentor、Sami 從 DocBlock 生成 HTML/API 文檔站點。
  • 屬性 (PHP 8.0+):#[Attribute] 逐步替代部分 DocBlock 元數據(如路由、驗證、ORM 映射)。

註釋反模式(避免)

// ❌ 無意義註釋
$i++; // i 加 1

// ❌ 過時註釋
// 連接 MySQL
$pdo = new Pgsql(...); // 實際連 PostgreSQL

// ❌ 註釋掉代碼留存(用版本控制替代)
/* $oldCode = ... */

結語

註釋解釋「為什麼」,代碼表達「做什麼」。遵循 DocBlock 標準、配合靜態分析工具、及時維護同步,讓註釋成為提升團隊效率的資產而非負債。

copyright © 萬盛學電腦網 all rights reserved