PHP 零基础教程

PHP 注释

在 PHP 中，注释是编写可维护和易于理解的代码的重要组成部分。它们允许开发者直接在脚本中包含笔记、解释或临时禁用某段代码，而 PHP 解析器在执行期间会完全忽略这些内容。这种做法显著提高了原始作者以及后续可能接手该代码的其他开发者的代码阅读体验。

1. 单行注释

单行注释用于简短的笔记或解释单行代码。PHP 支持两种主要的单行注释语法：// 和 #。它们的作用完全相同，即把从注释字符开始直到该行结束的所有内容标记为注释。

1.1 使用 // 进行单行注释

// 语法在许多编程语言中被广泛采用，也是 PHP 中单行注释的常见选择。在同一行中，紧随 // 之后的任何文本都将被视为注释。

<?php
echo "Hello, World!"; // 这行代码向浏览器输出一句问候。

$name = "Alice";
echo "我的名字是 " . $name; // 拼接字符串和变量以形成一个完整的句子。

// 这是一个独立的单行注释。
// 它描述了后续代码块的用途。
$age = 30;
echo "我今年 " . $age . " 岁。";
?>

在上面的例子中：

  • 第一个 // 注释解释了 echo "Hello, World!"; 语句的用途。
  • 第二个 // 注释阐明了字符串和变量是如何结合的。
  • 第三个和第四个 // 注释单独成行，用于描述后续代码部分的功能。

1.2 使用 # 进行单行注释

# 符号在 PHP 中同样表示单行注释，它继承自 Shell 脚本和 Perl。与 // 类似，从 # 开始到当前行末尾的所有内容都会被忽略。

<?php
$price = 100; # 初始化产品价格变量。
$quantity = 5;

# 计算总成本。
$total = $price * $quantity;

echo "总成本：$" . $total; # 显示总成本。
?>

在这里：

  • 第一个 # 注释描述了 $price 的初始化。
  • 第二个 # 注释单独成行，解释了接下来的计算过程。
  • 第三个 # 注释解释了输出语句。

虽然 // 和 # 对于单行注释都是有效的，但在现代 PHP 开发中，// 通常被认为是更常规和现代的代码风格。在一个项目中保持一致的注释风格是一个好习惯。

2. 多行注释

多行注释（也称为块注释）用于跨越多行的更详细的解释。它们以 /* 开始，以 */ 结束。这两个标记之间的所有文本，无论有多少换行，都会被视为注释。

2.1 多行注释的语法与用法

多行注释在以下场景中特别有用：

  • 提供对函数或复杂代码块的详细解释。
  • 包含版权信息或文件头说明。
  • 在调试期间临时禁用一段代码。
<?php
/*
此脚本演示了 PHP 中变量的使用和基本算术运算。
它初始化了两个数字变量，执行乘法运算，然后
将结果输出到浏览器。
作为“模块 1：PHP 基础入门”的一部分开发。
*/

$num1 = 25;
$num2 = 4;

/*
以下几行代码计算 $num1 和 $num2 的乘积。
结果存储在 $product 变量中。
此操作是许多财务或数据处理任务的基础。
*/
$product = $num1 * $num2;
echo $num1 . " 和 " . $num2 . " 的乘积是：" . $product;

/*
echo "这行代码已被注释掉，不会执行。";
$anotherVariable = 10;
echo "这行也不会执行：" . $anotherVariable;
*/
?>

在这个例子中：

  • 第一个多行注释提供了脚本目的和背景的全面概述，充当了文件头的角色。
  • 第二个多行注释详细解释了计算过程。
  • 最后一个多行注释演示了如何临时禁用代码块。该注释块内的任何 echo 或变量赋值语句都不会被 PHP 执行。

3. 实用案例与演示

了解何时以及如何有效地使用注释对于编写专业且可维护的 PHP 代码至关重要。

3.1 记录变量与常量

注释可以阐明变量的用途和预期值，特别是当它们的名称可能不够直观或它们具有特定重要性时。

<?php
// 定义当前美元对欧元的汇率。
// 此值可能会根据市场波动而变化。
$exchangeRateUSDToEUR = 0.92;

// 用户的首选货币设置，'USD' 或 'EUR'。
$userCurrencyPreference = "USD";

/*
以下变量代表客户在单次交易中
可以添加到购物车的最大商品数量。
执行此限制是为了管理库存和物流运输。
*/
$maxCartItems = 50;

echo "当前 USD 对 EUR 汇率：" . $exchangeRateUSDToEUR . "<br>";
echo "用户货币偏好：" . $userCurrencyPreference . "<br>";
echo "允许的最大购物车商品数：" . $maxCartItems . "<br>";
?>

3.2 解释复杂逻辑

对于更复杂的代码块，多行注释可以逐步拆解逻辑，让其他人（或未来的你自己）更容易理解代码背后的意图。

<?php
/*
此部分模拟了基本的库存检查。
它首先定义了可用库存，然后定义了客户请求的数量。
条件检查决定了是否可以满足请求的数量。
如果不能，则显示相应的提示信息。
*/
$availableStock = 150; // 当前库存中的总商品数。
$requestedQuantity = 10; // 客户想要购买的商品数量。

if ($requestedQuantity <= $availableStock) {
    // 如果库存充足，则继续处理“订单”。
    echo "可以满足 " . $requestedQuantity . " 件商品的订单。<br>";
    $remainingStock = $availableStock - $requestedQuantity;
    echo "剩余库存：" . $remainingStock . "<br>";
} else {
    // 如果库存不足，通知客户。
    echo "库存不足。仅有 " . $availableStock . " 件商品可用。<br>";
}

// 另一个根据角色 ID 检查用户是否为管理员的场景。
$userRoleID = 1; // 1 代表管理员，2 代表编辑，3 代表订阅者。

if ($userRoleID === 1) {
    echo "用户是管理员。"; // 授予管理员操作权限。
} else {
    echo "用户不是管理员。"; // 拒绝管理员操作权限。
}
?>

3.3 临时禁用代码

在开发或调试期间，经常需要临时禁用部分代码而不是直接删除它们。注释提供了一种安全的方法来实现这一点。

<?php
$debugMode = true;

if ($debugMode) {
    // 使用单行注释临时禁用特定的调试输出
    // echo "调试：脚本开始于 " . date("H:i:s") . "<br>";
}

/*
使用多行注释在测试期间禁用代码块。
这可能是一个数据库查询或繁重的计算，
我们不希望在开发期间反复运行它。

$databaseResult = fetchFromDatabase("users");
if ($databaseResult) {
    echo "成功获取用户。<br>";
} else {
    echo "获取用户失败。<br>";
}
*/

echo "应用程序逻辑在此继续。";
?>

在这个例子中，特定的 echo 语句和模拟的数据库操作被注释掉了，从而阻止了它们的执行。这对于隔离问题或测试脚本的不同部分特别有用。