注释

什么是注释？

在编程中，注释是程序员在代码中添加的说明性文字，这些文字不会被PHP解释器执行。注释的主要作用是：

解释代码功能：帮助自己和他人理解代码的用途
记录开发思路：在复杂逻辑处添加说明
临时禁用代码：在调试时暂时屏蔽某些代码行
提高代码可读性：让代码更易于维护

PHP中的注释类型

PHP支持三种注释方式：

1. 单行注释（//）

使用双斜线 //，从双斜线开始到行尾的内容都是注释。

<?php
// 这是一个单行注释
$name = "张三"; // 在变量后面也可以添加注释

// 下面的代码用来输出欢迎信息
echo "欢迎来到PHP世界！";

// echo "这行代码被注释了，不会执行";
?>

使用场景：

简短的说明
解释某行代码的作用
临时禁用单行代码

2. Shell风格单行注释（#）

使用井号 #，功能和 // 完全相同，但较少使用。

<?php
# 这也是一个单行注释（Shell风格）
$age = 25; # 设置年龄变量

# 计算明年年龄
$nextYearAge = $age + 1;

echo "明年你将 {$nextYearAge} 岁";
?>

使用场景：

在某些框架或约定中会使用
从Shell脚本转换过来的开发者可能习惯使用

3. 多行注释（/* ... */）

使用 /* 开始，*/ 结束，可以跨越多行。

<?php
/*
 * 这是一个多行注释
 * 可以写多行内容
 * 通常用于函数或类的详细说明
 */
$version = "1.0.0";

/*
功能：计算两个数的和
参数：$num1 - 第一个数
      $num2 - 第二个数
返回值：两个数的和
*/
function add($num1, $num2) {
    return $num1 + $num2;
}
?>

使用场景：

函数、类的详细说明
复杂算法的解释
版权信息和作者说明
临时禁用多行代码

注释的最佳实践

1. 注释应该"为什么"，而不是"什么"

// ❌ 不好的注释：重复代码内容
$name = "张三"; // 将"张三"赋值给name变量

// ✅ 好的注释：解释原因和目的
$name = "张三"; // 用户真实姓名，用于生成个性化欢迎消息

2. 保持注释简洁明了

// ❌ 过于冗长的注释
// 为了让系统知道当前的用户是谁，我们需要获取用户的姓名，
// 这样我们就可以在页面显示个性化的问候信息

// ✅ 简洁有效的注释
// 获取用户姓名用于个性化显示
$username = $_SESSION['user_name'];

3. 注释要与代码保持同步

// ❌ 注释与代码不符
// 计算用户年龄
$age = date('Y') - $birth_year + 1; // 实际计算的是周岁+1

// ✅ 注释准确反映代码功能
// 计算用户周岁年龄
$age = date('Y') - $birth_year;

4. 使用标准化的注释格式

函数注释示例：

<?php
/**
 * 计算两个数的乘积
 *
 * @param float $num1 第一个乘数
 * @param float $num2 第二个乘数
 * @return float 两数相乘的结果
 * @throws InvalidArgumentException 如果参数不是数字
 *
 * @example multiply(3, 5); // 返回 15
 */
function multiply($num1, $num2) {
    if (!is_numeric($num1) || !is_numeric($num2)) {
        throw new InvalidArgumentException("参数必须是数字");
    }

    return $num1 * $num2;
}
?>

类注释示例：

<?php
/**
 * 用户管理类
 *
 * 提供用户注册、登录、信息修改等功能
 *
 * @author 张三 <zhangsan@example.com>
 * @version 1.0.0
 * @since 2024-01-01
 */
class UserManager {
    /** @var string 数据库连接字符串 */
    private $dbConnection;

    /**
     * 构造函数
     *
     * @param string $dbHost 数据库主机地址
     * @param string $dbName 数据库名称
     */
    public function __construct($dbHost, $dbName) {
        // 构造数据库连接
        $this->dbConnection = "mysql:host={$dbHost};dbname={$dbName}";
    }
}
?>

实际应用示例

示例1：简单的用户信息处理

<?php
// ========================================
// 用户信息处理脚本
// 功能：获取、验证并显示用户信息
// 作者：张三
// 创建日期：2024-01-01
// ========================================

// 引入用户类文件
require_once 'User.php';

// 获取表单提交的数据
$username = $_POST['username'] ?? ''; // 使用空值合并运算符处理未提交的情况
$email = $_POST['email'] ?? '';
$age = $_POST['age'] ?? 0;

// 数据验证
if (empty($username)) {
    die('用户名不能为空'); // die()函数会输出错误信息并终止脚本
}

/*
 * 邮箱格式验证
 * 使用PHP内置的filter_var函数进行验证
 * FILTER_VALIDATE_EMAIL是专门用于验证邮箱的过滤器
 */
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    die('邮箱格式不正确');
}

// 年龄验证（必须是1-120之间的整数）
if (!is_numeric($age) || $age < 1 || $age > 120) {
    die('年龄必须是1-120之间的数字');
}

// 创建用户对象并保存信息
$user = new User();
$user->setName($username);      // 设置用户名
$user->setEmail($email);        // 设置邮箱
$user->setAge((int)$age);       // 设置年龄（强制转换为整数）

// 保存到数据库
try {
    $userId = $user->save(); // save()方法返回新用户的ID
    echo "用户注册成功！用户ID：{$userId}";
} catch (Exception $e) {
    // 捕获并处理可能的数据库错误
    echo "保存失败：" . $e->getMessage();
}

?>

示例2：配置文件注释

<?php
/* ========================================
 * 网站配置文件
 * 注意：修改配置后需要重启Web服务器
 * ======================================== */

// 数据库配置
define('DB_HOST', 'localhost');     // 数据库服务器地址
define('DB_NAME', 'my_website');    // 数据库名称
define('DB_USER', 'root');          // 数据库用户名
define('DB_PASS', 'password');      // 数据库密码

// 网站基本信息
define('SITE_NAME', '我的网站');     // 网站名称
define('SITE_URL', 'https://example.com'); // 网站URL
define('ADMIN_EMAIL', 'admin@example.com'); // 管理员邮箱

// 系统设置
define('DEBUG_MODE', true);         // 调试模式开关：true=开启，false=关闭
define('TIMEZONE', 'Asia/Shanghai'); // 时区设置
define('MAX_FILE_SIZE', 5242880);   // 最大文件上传大小（5MB）

// 缓存配置（单位：秒）
define('CACHE_DURATION', 3600);     // 缓存持续时间
define('SESSION_TIMEOUT', 1800);    // 会话超时时间

/*
 * API配置
 * 密钥和令牌等敏感信息建议放在环境变量中
 * 这里仅作示例说明
 */
define('API_KEY', 'your_api_key_here');
define('API_SECRET', 'your_api_secret_here');
?>

注释的常见错误和解决方案

1. 注释嵌套问题

<?php
/*
 * 外层注释开始
 *
 * // 这里是内层注释，没问题
 *
 * /* 这里是嵌套的多行注释 - 这会导致问题！ */
 * 外层注释在这里结束
 */

// ✅ 正确的做法：避免嵌套多行注释
/*
 * 第一段注释内容
 */

// 第二段独立的注释
/*
 * 第二段注释内容
 */
?>

2. HTML注释与PHP注释混淆

<?php
// HTML注释（在浏览器中可见）
echo '<!-- 这是HTML注释，用户可以在查看网页源代码时看到 -->';

// PHP注释（只在源代码中可见，不会发送到浏览器）
echo '<p>这是一段文本</p>'; // 这是PHP注释
?>

3. 在字符串中使用注释符号

<?php
$message = "这不是注释：// 也不是注释：/* 这里也不是注释 */";
echo $message; // 输出完整字符串内容

// 下面的才是真正的注释
$text = "Hello"; // 这是一个单行注释
?>

练习题

基础练习

注释类型识别 下面的代码中有哪些类型的注释？请标出来：

<?php
# 网站标题
$siteTitle = "学习PHP";

/*
 * 主函数
 * 返回欢迎消息
 */
function welcome($name) {
    return "Welcome, " . $name; // 拼接欢迎消息
}
?>

添加适当注释 为以下代码添加合适的注释：

<?php
$radius = 5;
$area = 3.14159 * $radius * $radius;
echo "半径为{$radius}的圆的面积是：{$area}";
?>

进阶练习

函数注释完善 为下面的函数添加完整的注释说明：

<?php
function calculateDiscount($originalPrice, $discountRate) {
    if ($originalPrice <= 0 || $discountRate <= 0 || $discountRate >= 1) {
        return false;
    }

    return $originalPrice * (1 - $discountRate);
}
?>

代码重构和注释 重构以下代码并添加适当注释：

<?php
$a = $_POST['x'];
$b = $_POST['y'];
if ($a > 0 && $b > 0) {
    $c = $a * $b;
    echo $c;
} else {
    echo "错误";
}
?>

实践练习

创建带注释的配置文件 创建一个配置文件，包含以下内容并添加详细注释：
- 数据库连接信息
- 文件上传限制
- 调试模式开关
- 时区设置
注释一个简单项目 创建一个简单的用户注册表单处理脚本，要求：
- 包含详细的文件头注释
- 每个主要步骤都有注释说明
- 函数有完整的文档注释
- 关键代码有行内注释

总结

良好的注释习惯是专业程序员的重要标志。记住以下几个要点：

注释要简洁明了，避免冗余
解释"为什么"而不是"什么"
保持注释与代码同步
使用标准化的注释格式
避免过度注释，好的代码本身就是最好的文档

注释的最终目的是让代码更容易理解和维护。随着经验的积累，你会逐渐掌握何时需要注释，如何写出有用的注释。

下一步学习：掌握注释后，让我们继续学习PHP中的变量与常量。

Begin to learn PHP.