16.4 代码规范与注释

为什么需要代码规范

代码规范是一组编写代码的规则和标准，它可以：

提高代码可读性：使代码更容易理解和维护
减少错误：规范的代码结构可以减少错误的发生
提高团队协作效率：统一的代码风格便于团队成员之间的协作
便于代码审查：规范的代码更容易进行代码审查
提高代码质量：规范的代码通常质量更高，更易于测试和维护

PHP 代码规范

1. 命名规范

变量命名

使用小写字母和下划线（snake_case）
变量名应该清晰、描述性，避免使用单个字母（除了循环变量）

php

// 好的命名
$user_id = 1;
$user_name = 'John Doe';

// 不好的命名
$uid = 1;
$un = 'John Doe';

函数命名

使用小写字母和下划线（snake_case）
函数名应该清晰、描述性，表明函数的用途

php

// 好的命名
function get_user_by_id($id) {
    // 函数实现
}

// 不好的命名
function getUser($id) {
    // 函数实现
}

类命名

使用大驼峰命名法（PascalCase）
类名应该清晰、描述性，表明类的用途

php

// 好的命名
class UserController {
    // 类实现
}

// 不好的命名
class user_controller {
    // 类实现
}

常量命名

使用全大写字母和下划线
常量名应该清晰、描述性

php

// 好的命名
define('MAX_USER_COUNT', 100);
const DEFAULT_PAGE_SIZE = 20;

// 不好的命名
define('max_user_count', 100);
const defaultPageSize = 20;

2. 代码缩进和格式

使用 4 个空格进行缩进（不要使用制表符）
大括号 { 应该放在行尾，而不是新行
代码行长度应该控制在 80-120 个字符以内

php

// 好的格式
function get_user($id) {
    if ($id > 0) {
        return find_user_by_id($id);
    } else {
        return null;
    }
}

// 不好的格式
function get_user($id)
{
    if($id>0)
    {
        return find_user_by_id($id);
    }
    else
    {
        return null;
    }
}

3. 代码结构

每个文件应该只包含一个类或一组相关的函数
代码应该按功能模块化，每个模块负责特定的功能
避免过长的函数，函数应该专注于单一职责

php

// 好的结构
// user.php
class User {
    // 用户相关方法
}

// user_controller.php
class UserController {
    // 用户控制器方法
}

// 不好的结构
// all_in_one.php
class User {
    // 用户相关方法
}

class UserController {
    // 用户控制器方法
}

function helper_function() {
    // 辅助函数
}

4. 注释规范

文件头部注释

每个文件应该有一个头部注释，说明文件的用途、作者、创建日期等信息。

php

<?php
/**
 * 用户控制器
 * 处理用户相关的请求
 * 
 * @author John Doe
 * @version 1.0
 * @since 2023-01-01
 */

函数注释

每个函数应该有注释，说明函数的用途、参数、返回值等信息。

php

/**
 * 根据用户 ID 获取用户信息
 * 
 * @param int $id 用户 ID
 * @return array 用户信息数组
 * @throws Exception 如果用户不存在
 */
function get_user_by_id($id) {
    // 函数实现
}

代码注释

在复杂的代码逻辑处添加注释，说明代码的意图和实现思路。

php

// 计算用户积分
// 基础积分 + 奖励积分 - 扣除积分
$total_points = $base_points + $bonus_points - $deduct_points;

// 检查用户是否达到升级条件
if ($total_points >= $upgrade_threshold) {
    // 执行升级操作
    upgrade_user_level($user_id);
}

5. 错误处理

使用 try-catch 块处理异常
不要使用 @ 符号抑制错误
记录错误信息，便于调试和排查

php

// 好的错误处理
try {
    $result = do_something();
} catch (Exception $e) {
    log_error($e->getMessage());
    echo "操作失败，请稍后重试";
}

// 不好的错误处理
@do_something(); // 抑制错误

6. 安全规范

防止 SQL 注入，使用预处理语句
防止 XSS 攻击，对输出进行转义
防止 CSRF 攻击，使用 CSRF 令牌
保护敏感信息，不要在代码中硬编码密码、API 密钥等

php

// 好的安全实践
$stmt = $conn->prepare("SELECT * FROM users WHERE id = ?");
$stmt->bind_param("i", $id);
$stmt->execute();

// 不好的安全实践
$sql = "SELECT * FROM users WHERE id = $id";
$result = mysqli_query($conn, $sql);

PHP 代码规范工具

1. PHP CodeSniffer

PHP CodeSniffer 是一个代码规范检查工具，可以检查代码是否符合指定的规范。

安装

bash

composer require --dev squizlabs/php_codesniffer

使用

bash

# 检查代码规范
./vendor/bin/phpcs --standard=PSR2 src/

# 自动修复代码规范问题
./vendor/bin/phpcbf --standard=PSR2 src/

2. PHP CS Fixer

PHP CS Fixer 是一个代码规范修复工具，可以自动修复代码中的规范问题。

安装

bash

composer require --dev friendsofphp/php-cs-fixer

使用

bash

# 修复代码规范
./vendor/bin/php-cs-fixer fix src/

3. IDE 插件

大多数 IDE 都有代码规范检查和自动修复的插件，如：

PhpStorm：内置代码规范检查和自动修复功能
VS Code：安装 PHP Intelephense、PHP CS Fixer 等插件
Sublime Text：安装 PHP CodeSniffer 插件

代码规范最佳实践

遵循 PSR 标准：PHP 社区推荐的代码规范标准，如 PSR-1、PSR-2、PSR-12
保持一致性：在整个项目中保持一致的代码风格
定期审查：定期进行代码审查，确保代码符合规范
自动化检查：使用 CI/CD 工具自动检查代码规范
培训团队：确保团队成员了解并遵循代码规范

实战演练

场景：重构一段不规范的代码

不规范的代码

php

<?php
function GetUser($ID){
    $sql="SELECT * FROM users WHERE id=$ID";
    $result=mysql_query($sql);
    if(!$result)return false;
    $user=mysql_fetch_array($result);
    return $user;
}

规范的代码

php

<?php
/**
 * 根据用户 ID 获取用户信息
 * 
 * @param int $id 用户 ID
 * @return array|false 用户信息数组或 false
 */
function get_user($id) {
    $stmt = $conn->prepare("SELECT * FROM users WHERE id = ?");
    $stmt->bind_param("i", $id);
    $stmt->execute();
    $result = $stmt->get_result();
    
    if (!$result) {
        return false;
    }
    
    $user = $result->fetch_assoc();
    return $user;
}

总结

代码规范是软件开发中的重要组成部分，它可以提高代码的可读性、可维护性和质量。通过遵循 PHP 代码规范，使用代码规范工具，以及实践代码规范最佳实践，可以写出更加规范、高质量的 PHP 代码。

在开发过程中，应该始终重视代码规范，将其作为开发流程的一部分，确保代码的质量和一致性。

16.4 代码规范与注释 ​

为什么需要代码规范 ​

PHP 代码规范 ​

1. 命名规范 ​

变量命名 ​

函数命名 ​

类命名 ​

常量命名 ​

2. 代码缩进和格式 ​

3. 代码结构 ​

4. 注释规范 ​

文件头部注释 ​

函数注释 ​

代码注释 ​

5. 错误处理 ​

6. 安全规范 ​

PHP 代码规范工具 ​

1. PHP CodeSniffer ​

安装 ​

使用 ​

2. PHP CS Fixer ​

安装 ​

使用 ​

3. IDE 插件 ​

代码规范最佳实践 ​

实战演练 ​

场景：重构一段不规范的代码 ​

不规范的代码 ​

规范的代码 ​

总结 ​

16.4 代码规范与注释

为什么需要代码规范

PHP 代码规范

1. 命名规范

变量命名

函数命名

类命名

常量命名

2. 代码缩进和格式

3. 代码结构

4. 注释规范

文件头部注释

函数注释

代码注释

5. 错误处理

6. 安全规范

PHP 代码规范工具

1. PHP CodeSniffer

安装

使用

2. PHP CS Fixer

安装

使用

3. IDE 插件

代码规范最佳实践

实战演练

场景：重构一段不规范的代码

不规范的代码

规范的代码

总结