PHP 註解 (Comments)

註解是程式碼中的說明文字，不會被 PHP 執行。註解可以用來解釋程式碼的功能、暫時停用某段程式碼，或為其他開發者提供說明。

單行註解

使用 //

<?php
// 這是單行註解
echo "Hello, World!";

echo "Hello";  // 這也是單行註解，放在程式碼後面
?>

使用 #

<?php
# 這也是單行註解
echo "Hello, World!";

echo "Hello";  # 可以放在程式碼後面
?>

// 和 # 效果相同，但 // 更常用。

多行註解

使用 /* */ 包圍多行註解：

<?php
/*
這是多行註解
可以跨越多行
用來寫比較長的說明
*/
echo "Hello, World!";

/* 也可以寫成一行 */
echo "Hello";
?>

<?php
/*
外層註解
/* 內層註解 */  // 這裡就結束了！
這行會被執行或產生錯誤
*/
?>

文件註解 (DocBlock)

DocBlock 是一種特殊的多行註解格式，用於為函數、類別、方法等產生文件。PHP 文件產生工具（如 phpDocumentor）和 IDE 都能識別 DocBlock。

<?php
/**
 * 計算兩數相加
 *
 * @param int $a 第一個數字
 * @param int $b 第二個數字
 * @return int 兩數相加的結果
 */
function add(int $a, int $b): int
{
    return $a + $b;
}

/**
 * 使用者類別
 *
 * @author Mike Lee
 * @version 1.0.0
 */
class User
{
    /**
     * 使用者名稱
     * @var string
     */
    private string $name;
    
    /**
     * 建立使用者
     *
     * @param string $name 使用者名稱
     */
    public function __construct(string $name)
    {
        $this->name = $name;
    }
    
    /**
     * 取得使用者名稱
     *
     * @return string 使用者名稱
     */
    public function getName(): string
    {
        return $this->name;
    }
}
?>

常用 DocBlock 標籤

註解的用途

解釋複雜的邏輯

<?php
// 使用 Sieve of Eratosthenes 演算法找出質數
function getPrimes(int $n): array
{
    // 初始化布林陣列，假設所有數字都是質數
    $isPrime = array_fill(2, $n - 1, true);
    
    // 從 2 開始，將所有倍數標記為非質數
    for ($i = 2; $i * $i <= $n; $i++) {
        if ($isPrime[$i]) {
            // 將 i 的所有倍數標記為非質數
            for ($j = $i * $i; $j <= $n; $j += $i) {
                $isPrime[$j] = false;
            }
        }
    }
    
    // 回傳所有標記為質數的數字
    return array_keys(array_filter($isPrime));
}
?>

標記待辦事項

<?php
function processData($data)
{
    // TODO: 加入資料驗證
    // FIXME: 這裡的效能需要優化
    // HACK: 暫時的解決方案，之後需要重構
    // NOTE: 這個函數只支援 UTF-8 編碼
    
    return $data;
}
?>

暫時停用程式碼

<?php
$price = 100;

// 舊的折扣計算方式
// $discount = $price * 0.1;

// 新的折扣計算方式
$discount = $price * 0.15;

echo "折扣金額：" . $discount;
?>

分隔程式碼區塊

<?php
// ==========================================
// 設定區
// ==========================================
$config = [
    'debug' => true,
    'timezone' => 'Asia/Taipei',
];

// ==========================================
// 資料庫連線
// ==========================================
$db = new PDO("mysql:host=localhost;dbname=test", "user", "pass");

// ==========================================
// 主程式
// ==========================================
// ... 主要邏輯
?>

良好的註解習慣

好的註解

<?php
// 計算使用者年齡（根據生日計算）
$age = calculateAge($birthday);

// 價格需要加上 5% 的稅
$totalPrice = $price * 1.05;

/**
 * 驗證 Email 格式
 * 使用 filter_var 而非正規表示式，因為更可靠
 */
function isValidEmail(string $email): bool
{
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}
?>

不好的註解

<?php
// 設定 x 為 5（這種註解沒有意義）
$x = 5;

// 遞增 i（程式碼本身就很清楚）
$i++;

// 迴圈
for ($i = 0; $i < 10; $i++) {
    // ...
}
?>

註解原則

1. 解釋「為什麼」而非「做什麼」：程式碼本身應該清楚說明做什麼，註解應該解釋為什麼這樣做
2. 保持註解更新：程式碼修改時，記得同步更新註解
3. 避免過度註解：好的程式碼應該自我說明，過多註解反而會造成干擾
4. 使用 DocBlock：為公開的函數和類別撰寫 DocBlock，方便其他開發者使用