PHP基础教程（50）PHP编码规范之命名规范：PHP起名大战：你的代码是相亲现场还是命名灾难？-优快云博客

朋友们，今天咱们不聊高深算法，不说复杂架构，就掰扯一个最基础、最要命、最能暴露程序员水平的事儿——起名字。

对，就是给你写的变量、函数、类起名字。这事儿有多重要？我打个比方：你去相亲，对面姑娘问你叫啥，你回一句：“我叫$a，我哥叫$b，我爸叫$c，我们家族还有$a1、$aa、$tmp……”你觉得你能找到对象吗？

你的代码，每天都被同事、接手者、甚至未来的自己“相亲”。一个糟糕的命名，轻则让人眉头紧锁、疯狂吐槽，重则引发线上故障、团队内战。而一套优雅规范的命名，就像一份清晰的说明书，是程序员最美的情书（至少对同事来说是）。

废话不多说，咱们直接开扒PHP命名规范的那些“江湖规矩”。

一、底层逻辑：为啥要规范？不是为了装X！

很多新手觉得：“我代码能跑就行了，搞这些花里胡哨的不是脱裤子放屁吗？” 大错特错！规范的核心目的就三个：

为了人类，不是机器：编译器才不管你叫$d还是$userDatabaseConnectionInstance，但你的队友需要一眼看懂这是啥。代码阅读频率远高于编写频率。
减少大脑缓存：好名字自带注释功能。看到calculateTotalPrice()，你还需要猜它干啥吗？而看到calc()，你可能得满世界找上下文。
形成团队方言：一个团队用同一种“说话方式”，沟通成本直线下降，新同学也能快速上车。这是工程效率，不是形式主义。

二、变量/属性名：你家变量是骆驼还是蛇？

这是重灾区。主要就两种流派：

1. 驼峰式（camelCase）：小驼峰，最常用

规则：第一个单词首字母小写，后面每个单词首字母大写。
场合：普通变量、对象属性、方法/函数参数。
口诀：像骆驼的背，起伏有致。

// ✅ 好的：清晰，具体
$userName = '张小明'; // 用户名
$orderItemList = []; // 订单项列表
$isPaymentCompleted = false; // 是否支付完成
$currentTimestamp = time(); // 当前时间戳
$dbConnection = null; // 数据库连接

// ❌ 坏的：令人窒息的操作
$un = '张小明'; // 缩写是万恶之源
$o_i_l = []; // 感觉在发电报
$f = false; // 哥们，你键盘`f`键是不是特别松？
$a = time(); // 一个月后你自己看得懂吗？
$tmp = getConnection(); // 万物皆可tmp，一tmp就永恒

2. 蛇形式（snake_case）：下划线连接

规则：所有字母小写，单词用下划线_连接。
场合：数据库字段名、配置文件键名、常量。在一些老代码或特定框架约定中，也用于变量。
口诀：像一条蛇，趴在地上。

// 数据库字段风格（通常对应蛇形）
$user_info = ['user_id' => 123, 'email_address' => 'test@example.com'];

// 配置键名
$config['db_host_name'] = 'localhost';
$config['max_retry_attempts'] = 3;

// 常量（PHP传统，虽然PSR建议大写蛇形，但小写蛇形配置很常见）
define('api_version', 'v1.0');

⚡ 重要抉择：团队统一用一种！别一会儿$userName，一会儿$user_name，精分会发作。

三、常量名：请用咆哮体！

常量，意味着一旦定义，生死不改。必须让它足够显眼，以示尊重（和警告）。

规则：全部大写，单词用下划线分割。
口诀：用喊的。

// ✅ 好的：隔着屏幕都能感受到它的不变
define('API_BASE_URL', 'https://api.xxx.com');
define('MAX_LOGIN_ATTEMPTS', 5);
define('SUPPORTED_CURRENCIES', ['USD', 'EUR', 'CNY']);
define('PROJECT_STATUS_ACTIVE', 1);

// ❌ 坏的：这居然是常量？改了会出事吗？
define('maxLimit', 100); // 看起来像变量
define('Site-Name', 'MySite'); // 还用了连字符，找死
$MAX_FILE_SIZE = 1024; // 用变量装常量，挂羊头卖狗肉

四、函数/方法名：请用动词开头！

函数和方法是做事情的，所以名字应该是一个动作或命令。

规则：小驼峰，并且第一个单词是动词。
口诀：动次打次，干事利索。

// ✅ 好的：一看就知道能干啥
function calculateOrderTotal(array $items): float {
    // 计算订单总额
}

function getUserById(int $userId): ?User {
    // 根据ID获取用户
}

function sendWelcomeEmail(User $user): bool {
    // 发送欢迎邮件
}

function isValidEmail(string $email): bool {
    // 验证邮箱是否有效
}

// ❌ 坏的：让人懵逼三连
function orderTotal(array $items): float { } // 名词开头，是属性吗？
function user(int $uid): ?User { } // 太模糊，获取？创建？删除？
function email(User $u): bool { } // 这是发邮件，还是收邮件，还是邮箱本身？
function check(string $str): bool { } // 检查啥？宇宙真理吗？

高级技巧：使用get（获取）、set（设置）、is/has（判断）、create（新建）、delete/remove（删除）、send（发送）、render（渲染）、handle（处理）等开头，准没错。

五、类名/接口名：要有贵族范儿！

类和接口是蓝图，是“人”或“物”。名字应该是一个名词或名词短语，体现其职责和身份。

规则：大驼峰（帕斯卡命名法），每个单词首字母都大写。
口诀：名门望族，字正腔圆。

// ✅ 好的：端庄，大气，上档次
class UserService { } // 用户服务
class OrderController { } // 订单控制器
class HttpClientFactory { } // HTTP客户端工厂
class PDOConnectionAdapter { } // PDO连接适配器
abstract class AbstractRepository { } // 抽象仓库
interface LoggerInterface { } // 日志器接口
trait SoftDeletes { } // 软删除特性

// ❌ 坏的：歪瓜裂枣，难当大任
class user { } // 首字母小写，像对象
class order_controller { } // 蛇形，不伦不类
class doSomething { } // 动词开头，这是函数干的事
class MyClass { } // “My”开头，散发着学生作业的气息

**命名空间（Namespace）**也遵循大驼峰，通常与目录结构对应，体现模块划分：

namespace App\Services\Payment;
namespace App\Models;
namespace App\Http\Controllers\Api\V1;

六、实战！看一个“规范”与“灾难”的对比

假设我们要实现一个功能：从数据库取用户订单，算总价，打九折，然后发邮件。

🚨 灾难版代码（阅读时请备好降压药）：

// 文件：`do.php` （这文件名就想打人）
class c1 {
    public $d; // 这啥？数据库？日期？
    
    public function f1($u_id) {
        $a = $this->d->q("select * from o where uid=" . $u_id); // SQL拼接！注入警告！
        $m = 0;
        foreach ($a as $v) { // $a, $v, $m... 字母表大战？
            $m += $v['p'];
        }
        $m2 = $m * 0.9;
        // 这里直接发邮件了？逻辑耦合！
        mail($u['e'], '价', '总价是' . $m2); // 邮件标题叫“价”？？？
        return $m2;
    }
}
// 调用：`(new c1())->f1(123);` —— 这是一段会召唤恶魔的咒语。

🌈 规范优雅版代码（强迫症室友看了直呼舒爽）：

// 文件：`app/Services/Order/OrderCalculatorService.php`
namespace App\Services\Order;

use App\Models\Order;
use App\Models\User;
use App\Mail\OrderSummaryMail;
use Illuminate\Support\Facades\Mail; // 假设用了Laravel的Mail

class OrderCalculatorService {
    private const DISCOUNT_RATE = 0.9; // 常量声明折扣率
    
    public function calculateDiscountedTotalForUser(int $userId): float {
        $orders = $this->getUserOrders($userId);
        $totalAmount = $this->calculateRawTotal($orders);
        $discountedAmount = $this->applyDiscount($totalAmount);
        
        return $discountedAmount;
    }
    
    public function calculateAndNotifyUser(int $userId): void {
        $discountedAmount = $this->calculateDiscountedTotalForUser($userId);
        $this->sendOrderSummaryEmail($userId, $discountedAmount);
    }
    
    // 私有方法，命名清晰
    private function getUserOrders(int $userId): array {
        // 使用ORM或查询构造器，安全！
        return Order::where('user_id', $userId)->get()->toArray();
    }
    
    private function calculateRawTotal(array $orders): float {
        $total = 0.0;
        foreach ($orders as $order) {
            $total += $order['price'];
        }
        return $total;
    }
    
    private function applyDiscount(float $amount): float {
        return $amount * self::DISCOUNT_RATE;
    }
    
    private function sendOrderSummaryEmail(int $userId, float $finalAmount): void {
        $user = User::find($userId);
        $mail = new OrderSummaryMail($user, $finalAmount);
        Mail::to($user->email)->send($mail);
    }
}

// 调用：`(new OrderCalculatorService())->calculateAndNotifyUser(123);`
// 即使不看内部实现，光看方法名就知道它在做什么。

七、特别提醒与避坑指南

不要用拼音！不要用拼音！不要用拼音！ $dingdan、$yonghuming 这是火星文吗？国际通用是英语。
慎用缩写：除非是ID、HTTP、URL这种全球共识的，否则请写全称。$custAddr 不如 $customerAddress 明白。
避免歧义：$data、$info、$result 这种“万金油”名字，只在非常局部的、作用明确的短代码中使用。泛泛而谈的名字承载了过多秘密。
一致性：如果你叫 getUser，那么同类方法就叫 getOrder、getProduct，不要变成 fetchAccount、retrieveItem。同一个概念，用一个词。
布尔值命名：用 is、has、can、should 开头。$isActive、$hasPermission、$canDelete，一看就是true/false。
长度平衡：别太短（$i），也别太长（$theUsersCurrentActiveOrderItemCollection）。一般3-20个字符是舒适区。