Clean Code en PHP: principios y ejemplos prácticos

Introducción: por qué el código limpio en PHP no es un lujo, sino una necesidad

Cada desarrollador PHP se ha enfrentado al menos una vez a una situación en la que un simple error en el entorno de producción se convierte en una cacería de horas en busca del "diablo en los detalles". La mayoría de las veces, la causa no radica en la complejidad de la lógica, sino en el código sucio: nombres de variables sin sentido, funciones de 500 líneas, falta de tipos y comentarios mentirosos. Clean Code (Código Limpio) no es solo estética. Es una herramienta que reduce el costo de mantenimiento del proyecto entre 3 y 5 veces y permite que los nuevos miembros del equipo se integren al proyecto en horas, no en semanas.

En este artículo, analizaremos los principios clave de Clean Code aplicados a PHP, respaldándolos con ejemplos reales de antes y después de la refactorización. Aprenderá cómo aplicar los estándares PSR, los principios SOLID y reglas simples de nomenclatura para que su código hable por sí mismo.

1. Nomenclatura de variables, funciones y clases: hable el idioma del negocio

Un mal nombre es el principal enemigo de la legibilidad. Si una variable se llama $a o $data, cada vez que lea el código, gastará recursos mentales en descifrarla. La regla es simple: el nombre debe responder a la pregunta "¿Qué es esto?" o "¿Qué hace?"

Ejemplo malo

<?php// ¿Qué es $d? ¿Por qué $x = 2?$d = new DateTime();$x = 2;$y = $d->modify('+' . $x . ' days');echo $y->format('Y-m-d');?>

Ejemplo bueno (Clean Code)

<?php$currentDate = new DateTime();$daysToAdd = 2;$futureDate = $currentDate->modify('+' . $daysToAdd . ' days');echo $futureDate->format('Y-m-d');?>

Reglas adicionales:

• Clases e interfaces — sustantivos: UserRepository, PaymentGatewayInterface.
• Métodos — verbos: getUserById(), sendEmailNotification().
• Variables booleanas — prefijos is, has, can: $isActive, $hasPermission.
• Evite abreviaturas: $cnt → $count, $usr → $user.

2. Funciones y métodos: principio de responsabilidad única (SRP) en acción

Una función, una acción. Si ve una función de más de 20–30 líneas, lo más probable es que se pueda dividir. En PHP esto es especialmente relevante, ya que la falta de tipificación estricta (hasta PHP 7.4) provoca "vertederos" de código.

Ejemplo malo: función navaja suiza

<?phpfunction processOrder(array $orderData): array{    // Validación    if (empty($orderData['email'])) {        throw new InvalidArgumentException('Email required');    }    // Guardar en BD    $pdo = new PDO('mysql:host=localhost;dbname=test', 'root', '');    $stmt = $pdo->prepare('INSERT INTO orders (email, total) VALUES (?, ?)');    $stmt->execute([$orderData['email'], $orderData['total']]);    // Enviar email    mail($orderData['email'], 'Order Confirmed', 'Thank you!');    // Registrar    file_put_contents('log.txt', 'Order processed: ' . $orderData['email'] . PHP_EOL, FILE_APPEND);    return ['status' => 'success'];}?>

Ejemplo bueno: separación de responsabilidades

<?phpclass OrderProcessor{    private OrderValidator $validator;    private OrderRepository $repository;    private MailService $mailer;    private Logger $logger;

    public function __construct(        OrderValidator $validator,        OrderRepository $repository,        MailService $mailer,        Logger $logger    ) {        $this->validator = $validator;        $this->repository = $repository;        $this->mailer = $mailer;        $this->logger = $logger;    }

    public function process(array $orderData): arr