萬盛學電腦網

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

PHP 註釋寫法完整指南:單行、多行與 PHPDoc 標準

三種基本註釋語法

語法類型範例
// ...單行(C++ 風格)// 作者:張三
# ...單行(Shell 風格)# 日期:2024-01-01
/* ... */多行(C 風格)/* 多行說明\n 可跨多行 */

程式碼範例

<?php
// 單行註釋:說明下一行用途
$name = 'PHP';

// 多行註釋:函式/類別說明
/*
 * 計算兩數總和
 * @param int $a
 * @param int $b
 * @return int
 */
function sum($a, $b) {
    return $a + $b;
}

// Shell 風格單行(較少見,但合法)
# 這也是單行註釋
echo sum(1, 2);

PHPDoc 文檔區塊(業界標準)

用於自動生成 API 文檔、IDE 智慧提示、靜態分析工具(PHPStan/Psalm)型別推斷。

/**
 * 使用者服務類別
 *
 * @package App\Service
 * @author  張三 <zhangsan@example.com>
 * @version 1.0
 */
class UserService {
    /**
     * 依 ID 取得使用者
     *
     * @param int $id 使用者 ID
     * @return User|null 使用者實體或 null
     * @throws \Exception 找不到時拋出
     */
    public function getById(int $id): ?User {
        // ...
    }
}

常用標籤速查

  • @param 參數說明(型別 變數名 說明)
  • @return 回傳值說明
  • @throws 可能拋出的異常
  • @var 屬性/變數型別
  • @method 魔術方法提示
  • @property 動態屬性提示
  • @deprecated 標記棄用
  • @see 參考連結

最佳實務

  1. 所有 public/protected 方法、類別、介面**必須**寫 PHPDoc。
  2. 私有方法視複雜度決定,建議至少寫單行說明。
  3. 保持註釋與程式碼同步更新,過期註釋比無註釋更有害。
  4. 使用 IDE(PhpStorm/VS Code + PHP Intelephense)自動產生骨架。
copyright © 萬盛學電腦網 all rights reserved