PHP基础教程（49）PHP编码规范之书写规则：你的PHP代码是“肥宅快乐码”还是“八块腹肌精英码”？

原创于 2025-12-05 10:29:33 发布 · 255 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#php #android #android studio

PHP基础教程专栏收录该内容

52 篇文章

订阅专栏

深夜，程序员老王盯着屏幕上前任留下的一坨没有缩进、命名随性的代码，第七次尝试理解abc和

aBc 到底哪个才是用户ID，他默默拿出保温杯，喝了一口枸杞茶，下定决心从今天起要写出让别人看得懂的代码。

01 为什么你的代码需要“健身教练”？

曾经，许多PHP初学者认为编码规范不过是“花架子”，对实际开发帮助不大。这种想法在单人小项目中或许还能蒙混过关，但在如今的Web开发世界里，大型项目需要团队协作，代码的可读性和可维护性直接决定了项目的生死。

想象一下这样的场景：新同事接手你的代码，看到满屏的 $a、$b、$c 变量，花括号忽上忽下，缩进时有时无。他可能需要花上一整天，只为搞清楚一个简单的函数到底在做什么。

这种时间浪费完全可以避免。遵循编码规范，就像给代码配备了GPS导航，让任何开发人员都能快速理解程序逻辑，理清代码状况。

统一的编码风格还能方便团队内部交流。当所有人都“说同一种语言”，代码审查、知识传递都会变得高效。更重要的是，良好的规范有助于长期维护，降低软件生命周期中的总成本。

02 基础体型塑造：书写规则的“黄金准则”

书写规则是编码规范中最基础也最直观的部分，它决定了代码的“第一印象”。

缩进是代码的骨架。主流的PHP编码规范通常建议使用4个空格进行缩进。虽然有些团队可能选择2个空格，但关键是保持一致性——整个项目必须使用同一种缩进方式。

花括号的摆放位置一直是程序员界的“甜咸之争”。主要有两种流派：一是将左花括号放在关键字下方、同列；二是左括号与关键词同行，右括号与关键字同列。

无论选择哪种风格，统一是关键。混合使用不同风格会让代码看起来像打了补丁的旧衣服。

空格的使用也很讲究。圆括号和关键字之间应该用空格隔开，但圆括号和函数名要紧贴在一起，这样能清晰地区分关键字和函数调用。

对于运算符，两边都应留有一个空格（字符连接运算符“.”除外）。例如 $sum = $a + $b; 就比 $sum=$a+$b; 更易读。

03 代码的“呼吸系统”：合理使用空白与换行

代码不是越紧凑越好，恰当的空白和换行就像文章的段落分隔，让逻辑结构一目了然。

PHP解析器会忽略代码中的空格、回车和Tab键，这给了我们利用空白提升可读性的自由。但自由不等于随意，空白的使用也需要遵循一定规范。

在以下情况应该总是使用两个空白行：两个类的声明之间，以及一个源文件的两个代码片段之间。

一个空白行则适用于：两个函数声明之间、函数内的局部变量和函数的第一个语句之间、块注释或单行注释之前，以及一个函数内的两个逻辑代码段之间。

换行的艺术同样重要。当一行代码超过80个字符时，应当考虑换行。比如链式方法调用或长数组定义，适当换行可以大幅提升可读性。

// 不推荐的写法，一行太长
$result = $this->db->select('id')->where('a', 1)->groupBy('a')->orderBy('id', 'DESC')->result();

// 推荐的写法，清晰易读
$result = $this->db->select('id')
    ->where('a', 1)
    ->groupBy('a')
    ->orderBy('id', 'DESC')
    ->result();

04 命名之道：给变量起个好名字

命名是编程中最难的两件事之一（另一件是缓存失效）。好的命名能让代码自我解释，减少注释的必要。

类名应该使用大驼峰式（StudlyCaps）命名法，即每个单词首字母大写，如 UserController、DatabaseConnection。类名应当使用名词或名词短语，反映类所代表的实体。

方法名则应采用小驼峰（camelCase）命名法，即第一个单词全小写，后续单词首字母大写，如 getUserName()、calculateTotalPrice()。方法名通常使用动词或动词短语，表明方法执行的动作。

对于变量命名，规范略有分歧。有些规范建议使用小写字母加下划线，如 $user_name；而现代PHP实践更倾向于小驼峰命名法，如 $userName。选择哪种风格并不绝对，项目一致性才是关键。

常量命名则毫无争议——全部使用大写字母，单词间用下划线分隔，如 MAX_LOGIN_ATTEMPTS、DEFAULT_PAGE_SIZE。

05 注释的艺术：不多不少刚刚好

代码告诉你“怎么做”，注释告诉你“为什么这么做”。好的注释不是重复代码，而是补充代码无法表达的信息。

PHP支持多种注释风格：C风格的多行注释 /* ... */，C++风格的单行注释 //，以及Shell风格的 #。现代PHP开发中，// 用于单行注释，/* ... */ 用于多行注释是最常见的做法。

类注释应该包含类的功能描述、作者信息和创建时间。方法注释则需要说明方法功能、参数含义和返回值。

/**
 * 用户认证处理类
 * @author ZhangSan
 * @since 2023-06-01
 */
class UserAuth
{
    /**
     * 验证用户登录凭证
     * @param string $username 用户名
     * @param string $password 密码
     * @return bool 验证结果
     */
    public function validateCredentials($username, $password)
    {
        // 具体的验证逻辑
    }
}

对于临时调试代码，有些人喜欢用注释“禁用”一段代码。这里有个小技巧：使用 /*if(...)//*/ 的注释方式，需要恢复时只需删除开头的 /*，比重新添加 // 到每一行要高效得多。

06 控制结构：if、switch和循环的优雅写法

控制结构是程序的决策点，规范的写法能让逻辑更加清晰。

对于if-elseif-else结构，关键字与括号之间应有一个空格，左花括号与右括号之间也应有一个空格。

// 规范写法
if ($expr1) {
    // if 与 ( 之间有一个空格，) 与 { 之间有一个空格
} elseif ($expr2) {
    // elseif 连着写，不是 else if
} else {
    // else 左右各一个空格
}

switch语句的规范同样重要。case语句应该从switch处缩进一级，而case内部的代码再缩进一级。

switch ($value) {
    case 1:
        echo 'First case';
        break;
    case 2:
        echo 'Second case';
        // 故意不写 break 时应有注释说明
        // no break
    default:
        echo 'Default case';
        break;
}

每个switch语句都应该包含default分支，即使它什么都不做。这有助于处理未预期的值，提高代码的健壮性。

07 文件与编码：容易被忽视的细节

文件级别的规范往往被忽视，但它们同样重要，特别是在团队协作和跨平台环境中。

纯PHP文件不应包含结束标签?>。这是因为结束标签后的任何空格或换行都可能导致意外的输出，特别是在处理HTTP头信息时。省略结束标签还能防止文件末尾意外添加的空格或空行。

文件编码应统一使用UTF-8 without BOM。带BOM（字节顺序标记）的UTF-8编码可能在PHP中产生预期之外的输出，影响应用程序设置自己的HTTP头信息。

对于包含PHP和HTML混合的文件，PHP代码应使用完整的 <?php ... ?> 标签定界，短标签 <? ... ?> 不被允许。这确保了代码在不同PHP配置环境下的兼容性。

08 现代PHP实践：PSR标准与类型声明

随着PHP语言的发展，一些新的最佳实践逐渐成为行业标准。

PHP-FIG（PHP Framework Interop Group）制定的PSR标准是目前最广泛接受的PHP编码规范。PSR-1和PSR-12分别定义了基本的编码标准和扩展的代码风格指南，是PHP项目的良好起点。

类型声明是PHP 7引入的重要特性，它可以提高代码的清晰度和可靠性。所有新函数都应使用类型提示和返回类型声明。

// 现代PHP写法
public function calculateTotal(float $price, int $quantity): float
{
    return $price * $quantity;
}

严格类型模式也是现代PHP的推荐实践。通过在文件开头添加 declare(strict_types=1);，可以启用严格类型检查，避免一些隐蔽的类型转换错误。

09 完整示例：从混乱到规范

让我们通过一个完整示例，看看规范如何让代码焕然一新。

不规范版本：

<?php
class user{ // 类名未使用大驼峰，花括号位置不规范
function getinfo($id){ // 方法名未使用小驼峰，参数命名随意
$n=db::query("select name,age from users where id=$id"); // 变量命名随意，SQL直接拼接有安全隐患
return $n[0];}
}
?>

规范版本：

<?php
declare(strict_types=1);

/**
 * 用户信息处理类
 * @author LiSi
 * @since 2023-12-05
 */
class UserInfoHandler
{
    /**
     * 根据用户ID获取用户信息
     * @param int $userId 用户ID
     * @return array 用户信息数组
     * @throws PDOException 数据库查询异常
     */
    public function getUserInfo(int $userId): array
    {
        // 使用预处理语句防止SQL注入
        $sql = "SELECT name, age FROM users WHERE id = :user_id";
        $statement = Database::prepare($sql);
        $statement->execute([':user_id' => $userId]);
        
        $userData = $statement->fetch(PDO::FETCH_ASSOC);
        
        if (empty($userData)) {
            return [];
        }
        
        return $userData;
    }
}

规范版本不仅更易读，而且更安全、更健壮。它使用了预处理语句防止SQL注入，添加了类型声明和异常处理，注释完整，命名清晰。

当规范成为习惯，你会发现自己的代码不再需要频繁重构，团队合作变得顺畅，即使是三个月前的代码，也能快速理解。

编程规范的价值不在于束缚创造力，而在于释放团队的协作潜力。如同交通规则让道路更安全高效，编码规范让代码世界更加有序可预测。

正如一位资深开发者所说：“你可以看不爽别人的代码，但是不要随意修改别人的代码，因为别人看你的代码也不爽。” 在统一的规范下，这种摩擦会大大减少，团队的每个成员都能更专注于创造价值，而非解读谜题。