Código limpio en PHP: guía para escribir como un profesional

Introducción: por qué el "código limpio" no es pedantería, sino dinero y tranquilidad

Imagina que entras a un proyecto antiguo en PHP, escrito hace un año. Abres el archivo index.php y te encuentras con una mezcla de HTML, consultas SQL, echos y funciones con nombres como f1(). ¿Te suena familiar? Si es así, o eres un principiante que empieza su camino, o un desarrollador experimentado al que le tocó un proyecto "legado".

El código limpio en PHP no es una moda ni un capricho del líder técnico. Es una herramienta que ahorra horas, nervios y dinero. En este artículo, veremos cómo transformar tu código PHP de un "borrador sucio" a una "versión final" que te hará feliz a ti y a tus compañeros. Hablaremos de los estándares PSR, los principios SOLID, la nomenclatura correcta y daremos ejemplos reales. ¡Allá vamos!

1. Filosofía del código limpio: principios fundamentales

Antes de sumergirnos en la sintaxis, pongámonos de acuerdo en las reglas del juego. El código limpio es aquel que:

\n
• Se entiende sin comentarios (aunque a veces los comentarios son necesarios).
\n
• Es fácil de probar.
\n
• No le teme a la refactorización.
\n
• Sigue un estilo uniforme en todo el proyecto.
\n

Robert Martin (Tío Bob) dijo en su libro "Código Limpio": "La única forma de ir rápido es ir bien". Si escribes rápido y desordenado, en un mes estarás dedicando 10 veces más tiempo a depurar. Aprendamos de los errores ajenos, no de los propios.

2. Estándares PSR: tu primer paso hacia el orden

En el mundo de PHP existen los PSR (PHP Standards Recommendations), que son recomendaciones adoptadas por la comunidad. Si no los usas, al menos le complicas la vida a tus compañeros y a ti mismo cuando tengan que leer tu código.

2.1 PSR-1 y PSR-12: Estilo básico de codificación

PSR-1 establece las reglas generales, y PSR-12 es el estilo extendido. Estos son algunos puntos clave:

\n
• Los archivos deben usar solo <?php o <?=.
\n
• La codificación de archivos debe ser UTF-8 sin BOM.
\n
• Los nombres de clases deben usar StudlyCaps (ejemplo: UserController).
\n
• Los nombres de métodos y propiedades deben usar camelCase (ejemplo: getUserName()).
\n
• La indentación debe ser de 4 espacios (¡no tabulaciones!).
\n

Ejemplo de código malo:

<?\nclass user_controller {\n\tfunction Get_User_Name($id) {\n\t\t$name = Db::query("SELECT name FROM users WHERE id=$id");\n\t\treturn $name;\n\t}\n}\n

Ejemplo de código bueno (PSR-12):

<?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Controllers;\n\nuse App\\Models\\User;\n\nclass UserController\n{\n    public function getUserName(int $id): ?string\n    {\n        $user = User::find($id);\n        return $user ? $user->getName() : null;\n    }\n}\n

¿Ves la diferencia? La segunda opción se lee como un libro: queda claro de inmediato qué hace el método, qué tipos de datos recibe y qué devuelve.

2.2 PSR-4: Autocarga de clases

Olvídate de los require_once en cada archivo. Usa Composer y PSR-4. Esto permite cargar clases automáticamente según el espacio de nombres. La estructura de carpetas debe coincidir con los namespaces:

src/\n  App/\n    Controllers/\n      UserController.php\n    Models/\n      User.php\n    Services/\n      PaymentService.php\n

En composer.json se configura con una sola línea:

{\n    "autoload": {\n        "psr-4": {\n            "App\\\\": "src/"\n        }\n    }\n}\n

3. Nomenclatura correcta: cómo no llamar a una variable $a

La nomenclatura es el 50% del éxito. Un mal nombre de variable puede confundir hasta a un genio. Veamos los errores más comunes.

3.1 Evita las abreviaturas (excepto las obvias)