Cómo escribir código limpio en PHP: reglas fundamentales

Escribir código limpio en PHP significa reducir errores, acelerar el mantenimiento y hacer que los proyectos sean más sostenibles a lo largo del tiempo. En esta guía veremos las reglas fundamentales: el estándar PSR-12, formato y nombres, tipos y modo estricto, gestión de errores, pruebas y los principios SOLID aplicados a casos reales, con ejemplos concretos.

El “código limpio” en PHP no es un capricho estético: es una elección técnica que afecta al mantenimiento, los errores, los tiempos de desarrollo y la colaboración. En la práctica, es lo que te permite volver a un proyecto después de meses (o pasarlo a otro desarrollador) sin tener que «descifrarlo» como si fuera un mensaje en una botella.

En esta guía, ordenamos las reglas fundamentales para escribir código limpio en PHP: estándares de formato y convenciones, tipos y modo estricto, gestión de errores, organización del proyecto, pruebas y principios SOLID aplicados. El objetivo es uno: escribir código más legible, más predecible y más fácil de cambiar.

1) Empieza con un estándar: PSR-12 y coherencia antes que estilo

El primer paso hacia un código limpio es sencillo: elige un estándar y respétalo siempre. En PHP, el estándar más común para el estilo de código es PSR-12 (PHP-FIG), que define directrices sobre indentación, espaciado, declaraciones, organización del código y mucho más. :contentReference[oaicite:0]{index=0}

El estándar no sirve para «ganar discusiones» en el equipo: sirve para reducir la fricción, hacer el código uniforme y permitir que las herramientas automáticas hagan el trabajo sucio (formateo y comprobaciones).

Reglas prácticas (que marcan la diferencia)

• Indentación coherente (normalmente 4 espacios, sin tabulaciones).
• Espaciado legible alrededor de los operadores y entre bloques lógicos.
• Una línea vacía entre métodos para separar secciones.
• Visibilidad siempre declarada (public/private/protected) para propiedades y métodos.

Estas directrices a menudo se resumen también en buenas prácticas de formato para clases y métodos, como en el ejemplo de referencia que cita PSR-12 como estándar oficial. :contentReference[oaicite:1]{index=1}

2) Naming: si un nombre es vago, el código ya es más difícil

El código limpio empieza por los nombres. Un nombre equivocado «oculta» el significado y obliga a quien lee a reconstruir mentalmente la intención. En PHP, una convención muy utilizada es:

• Clases en PascalCase (ej. OrderService)
• Métodos y variables en camelCase (ej. calculateTotal())

Es una regla simple, pero sobre todo sirve la coherencia. También aquí, las directrices básicas (clases PascalCase, métodos camelCase) son un punto firme del formato ordenado. :contentReference[oaicite:2]{index=2}

Checklist naming (rápida y útil)

• Prefiere nombres específicos (no $data, sino $orderData).
• Los métodos deberían empezar con un verbo (create, build, validate ).
• Evita abreviaturas crípticas: ahorras 2 caracteres y cuestan 20 minutos.

3) Tipos y modo estricto: menos ambigüedad, menos errores

PHP hoy permite una tipificación mucho más robusta que en el pasado. Si quieres código limpio, aprovecha:

• type hints para parámetros y return
• strict_types cuando tenga sentido
• property types y constructor promotion

<?php
declare(strict_types=1);

final class PriceCalculator
{
    public function calculateTotal(float $net, float $vatRate): float
    {
        return $net * (1 + $vatRate);
    }
}

Este enfoque hace la API de la clase más clara, reduce conversiones implícitas y ayuda a las herramientas de análisis estático.

4) Funciones pequeñas, responsabilidades únicas: el principio que siempre paga

Un indicador inmediato de «código sucio» es una función que hace demasiadas cosas: valida, transforma, guarda en DB, envía correos y quizá escribe logs. Cuando todo está dentro del mismo método, cada cambio se vuelve riesgoso.

Aquí entra en juego el primer principio SOLID, el Single Responsibility Principle (SRP): una clase debería tener una sola razón para cambiar. :contentReference[oaicite:3]{index=3}

Ejemplo (antes: todo junto, difícil de mantener)

final class OrderController
{
    public function checkout(array $payload): void
    {
        // valida input
        // calcola totali
        // salva ordine
        // invia email
        // logga operazione
    }
}

Después: responsabilidades separadas (más limpio, testeable)

final class CheckoutService
{
    public function __construct(
        private OrderValidator $validator,
        private OrderRepository $repository,
        private Mailer $mailer,
        private LoggerInterface $logger
    ) {}

    public function checkout(OrderRequest $request): void
    {
        $this->validator->validate($request);

        $order = Order::fromRequest($request);

        $this->repository->save($order);
        $this->mailer->sendOrderConfirmation($order);
        $this->logger->info('Order created', ['id' => $order->id()]);
    }
}

No es «más largo»: es más claro. Y sobre todo es más fácil de testear.

5) SOLID en PHP: qué cambia realmente en la práctica

Los principios SOLID son cinco guías de diseño orientado a objetos (OOP) pensadas para hacer el código más mantenible, extensible y robusto. :contentReference[oaicite:4]{index=4}

S – Single Responsibility (una responsabilidad)

Una clase no debería convertirse en un «contenedor de todo». Si crece demasiado, sepárala en componentes más pequeños y enfocados.

O – Open/Closed (abierto a extensiones, cerrado a modificaciones)

Cuando añades una feature, intenta extender sin modificar el comportamiento existente (reduce regresiones). Ejemplo típico: estrategias, manejadores, proveedores.

L – Liskov Substitution (sustituibilidad)

Si una subclase rompe las expectativas de la clase base, la jerarquía está mal. Si te ves forzado a «lanzar excepciones» porque un método no tiene sentido en la subclase, estás marcando un problema de diseño.

I – Segregación de Interfaces (interfaces pequeñas)

Mejor más interfaces pequeñas que una enorme que obliga a las clases a implementar métodos inútiles.

D – Inversión de Dependencias (depender de abstracciones)

Las clases de alto nivel deberían depender de interfaces, no de clases concretas. Esto reduce el acoplamiento y mejora la testeabilidad.

Si quieres un resumen claro de los cinco principios y sus definiciones, también es útil una fuente sintética (con la lista completa y el significado de cada letra). :contentReference[oaicite:5]{index=5}

6) Evita los «números mágicos» y las constantes dispersas

Otro clásico del código difícil: números y cadenas de texto repetidos por todas partes. Si un valor es significativo, dale un nombre.

final class Invoice
{
    private const VAT_STANDARD = 0.22;

    public function vatRate(): float
    {
        return self::VAT_STANDARD;
    }
}

Es una buena práctica simple y muy citada en las reglas de formato y organización del código. :contentReference[oaicite:6]{index=6}

7) Manejo de errores: excepciones, mensajes claros, nada de silencios

Código limpio también significa errores limpios. Pautas prácticas:

• Usa excepciones para errores «excepcionales», no para el flujo normal.
• No suprimas errores con@.
• Escribe mensajes que realmente ayuden a entender el problema.

throw new DomainException('Order total cannot be negative.');

Si un error no deja rastro, se convierte en un bug «fantasma»: costoso.

8) Comentarios: menos, pero mejores

Los comentarios no deben explicar «qué hace el código» si el código ya es claro. Deben explicar:

• por qué se tomó una decisión
• un requisito de negocio
• un caso límite no obvio

Incluso en las guías de formato se insiste en comentarios claros y concisos para lógicas complejas. :contentReference[oaicite:7]{index=7}

9) Automatiza el estilo: formateadores y linters

La disciplina manual no escala. En un proyecto real conviene automatizar:

• PHP-CS-Fixer o PHP_CodeSniffer(con reglas PSR-12)
• PHPStan o Psalmpara análisis estático
• hooks de pre-commit o CI para bloquear código no conforme

Resultado: menos discusiones en la revisión y más tiempo en arquitectura y calidad.

10) Prueba: el verdadero multiplicador de la limpieza

Si el código no es testeable, a menudo no está limpio. No porque «falten las pruebas», sino porque está demasiado acoplado, demasiado grande o demasiado dependiente del entorno.

Cuando aplicas principios como SRP e Inversión de Dependencias, las pruebas unitarias se vuelven más fáciles. Y cuando las pruebas son fáciles, el refactor se vuelve sostenible.

Conclusión

Escribir código limpio en PHP significa adoptar estándares (como PSR-12), cuidar la nomenclatura y el formato, reducir la ambigüedad con los tipos, gestionar errores de forma explícita y diseñar con responsabilidades claras. Los principios SOLID no son teoría: son una brújula práctica para escribir código más fácil de mantener, extender y probar con el tiempo. Si quieres un objetivo concreto: haz que el código sea legible, predecible y aburrido (en el mejor sentido). Así es como se vuelve profesional.

Pubblicato in PHP