Escribiendo código con reglas: Code Style y convenciones PHP para el equipo

Trabajo en equipo: code style y convenciones para PHP

Imagina que entras en un proyecto PHP ajeno. Abres un archivo y ves tabulaciones mezcladas con espacios, variables con nombres aleatorios y llaves colocadas en cualquier lugar menos donde estás acostumbrado. ¿Te suena familiar? Ahora imagina que hay cientos de archivos así, y cada uno fue escrito por un desarrollador diferente. Una pesadilla para el code review y el mantenimiento del código.

En este artículo analizaremos por qué el code style PHP y las convenciones de código no son solo un capricho del desarrollador senior, sino la base de un trabajo en equipo eficaz. Conocerás los estándares PSR, las reglas de nomenclatura, el formato y obtendrás ejemplos reales que puedes aplicar de inmediato en tu proyecto.

¿Por qué es importante el code style para el equipo?

Cuando varios desarrolladores trabajan en un proyecto, un estilo de código unificado se convierte en un salvavidas. He aquí por qué:

\n
• Legibilidad. El código escrito con reglas uniformes es fácil de leer para cualquier miembro del equipo. No hay que adivinar qué quiso decir el autor.
\n
• Velocidad del code review. Si el código tiene el mismo formato, el revisor se centra en la lógica, no en el formato.
\n
• Menos errores. Las convenciones uniformes reducen la probabilidad de errores relacionados con diferentes enfoques al escribir código.
\n
• Incorporación sencilla. Un nuevo desarrollador se integra más rápido en el proyecto si el código es predecible y está estructurado.
\n

En esencia, los estándares de codificación PHP son el idioma que habla todo el equipo. Cuanto más uniforme sea, menos malentendidos habrá.

Estándares principales: PSR y más

En el mundo de PHP existen varias recomendaciones clave que se han convertido en estándares de facto. Las más importantes son PSR-1 y PSR-12 (anteriormente PSR-2). Son compatibles con PHP-FIG (Framework Interoperability Group).

PSR-1: Reglas básicas

PSR-1 describe las reglas más generales: cómo nombrar clases, métodos, constantes y cómo organizar los archivos.

Puntos principales:

\n
• Los archivos deben usar solo <?php o <?= (etiqueta corta para salida).
\n
• La codificación del archivo debe ser UTF-8 sin BOM.
\n
• Nombres de clases en StudlyCaps (PascalCase).
\n
• Nombres de métodos en camelCase.
\n
• Constantes en mayúsculas con guiones bajos (MAX_VALUE).

Ejemplo de código correcto según PSR-1:

<?php\n\nnamespace App\\Services;\n\nclass UserService\n{\n    const DEFAULT_ROLE = 'user';\n\n    public function getUserById(int $id): ?User\n    {\n        // lógica\n    }\n\n    public function isAdmin(): bool\n    {\n        // lógica\n    }\n}

PSR-12: Reglas de estilo avanzadas

PSR-12 es la evolución de PSR-2. Añade más detalles sobre el formato.

Puntos clave:

\n
• Sangría: 4 espacios (no tabulaciones).
\n
• Las llaves de apertura van en la misma línea para clases, métodos y estructuras de control (estilo K&R).
\n
• Después de palabras clave (if, else, while) es obligatorio un espacio.
\n
• Línea en blanco después de la declaración de namespace y antes de return en métodos (opcional).
\n
• La línea no debe superar los 120 caracteres (se recomiendan 80).

Ejemplo de formato correcto según PSR-12:

<?php\n\nnamespace App\\Controllers;\n\nuse App\\Models\\User;\nuse App\\Services\\AuthService;\n\nclass AuthController\n{\n    private AuthService $authService;\n\n    public function __construct(AuthService $authService)\n    {\n        $this->authService = $authService;\n    }\n\n    public function login(array $credentials): bool\n    {\n        if (empty($credentials['email']) || empty($credentials['password'])) {\n            return false;\n