Documentación en PHP: cómo escribir código que se explica solo

¿Por qué tu proyecto PHP está condenado sin documentación?

Imagina que abres un proyecto que escribiste hace seis meses. Montones de archivos, nombres de variables extraños y, lo peor de todo, ni un solo comentario. ¿Te suena familiar? Ahora imagina que tienes que entregarle ese proyecto a un nuevo miembro del equipo o, peor aún, a un cliente. Sin documentación, se convierte en un juego de "Adivina qué hace este método".

En la comunidad PHP hay una regla no escrita: un buen código está documentado de forma que cualquier desarrollador nivel Junior pueda entenderlo. No se trata de escribir poemas en los comentarios, sino de un sistema que te ahorre horas de vida.

En este artículo, analizaremos las mejores prácticas para documentar proyectos PHP. Aprenderás cómo hacer que tu código hable por sí solo y que la documentación sea útil, no un dolor de cabeza.

PHPDoc: tu herramienta principal

Empecemos por lo básico. PHPDoc es el estándar para anotar código en PHP. Es compatible con la mayoría de los IDE (PhpStorm, VS Code) y herramientas como phpDocumentor. Si aún no usas PHPDoc, estás perdiendo tiempo descifrando tu propio código.

Cómo formatear bloques PHPDoc correctamente

La plantilla básica para una función o método se ve así:

/**\n * Descripción breve de lo que hace la función.\n *\n * Descripción detallada (opcional), si necesitas explicar lógica compleja.\n *\n * @param string $name Nombre del usuario.\n * @param int $age Edad del usuario (opcional).\n * @return string Mensaje de bienvenida.\n *\n * @throws \\InvalidArgumentException Si el nombre está vacío.\n */\nfunction greetUser(string $name, int $age = 0): string\n{\n    if (empty($name)) {\n        throw new \\InvalidArgumentException('El nombre no puede estar vacío');\n    }\n    \n    $greeting = "¡Hola, {$name}!";\n    if ($age > 0) {\n        $greeting .= " Tienes {$age} años.";\n    }\n    \n    return $greeting;\n}

Puntos clave:

\n
• @param — describe el tipo y propósito de cada argumento.
\n
• @return — indica el tipo de valor devuelto y su significado.
\n
• @throws — enumera las excepciones que puede lanzar el método. Esto evitará sorpresas en tiempo de ejecución.
\n

Anotaciones para propiedades de clases

Las propiedades también deben documentarse, especialmente si tienen tipos complejos:

class UserService\n{\n    /**\n     * Repositorio de usuarios para trabajar con la BD.\n     *\n     * @var UserRepositoryInterface\n     */\n    private UserRepositoryInterface $userRepository;\n\n    /**\n     * Caché para almacenar resultados de búsqueda.\n     *\n     * @var CacheInterface|null\n     */\n    private ?CacheInterface $cache = null;\n}

Observa que usamos @var para indicar el tipo. Incluso si tienes tipado estricto (PHP 7.4+), la anotación ayuda al IDE y a los analizadores estáticos.

Errores típicos en PHPDoc (y cómo evitarlos)

Incluso los desarrolladores experimentados cometen errores. Estos son los más comunes:

\n
• Bloques vacíos: /** */ antes de una función es basura inútil. O escribe algo con sentido o elimínalo.
\n
• Información desactualizada: cambiaste la firma del método pero olvidaste actualizar el PHPDoc. Resultado: desinformación. Siempre sincroniza la documentación con el código.
\n
• Redundancia: no escribas @return string si ya se ve que la función devuelve un string. PHPDoc debe explicar el significado, no duplicar el tipo.
\n

README: la cara de tu proyecto

PHPDoc es documentación interna para desarrolladores. Pero el README.md es lo que ve todo el mundo: desde colegas hasta visitantes ocasionales de GitHub. Un buen README responde tres preguntas:

\n
1. ¿Qué es esto? — una descripción breve del proyecto.
\n
2. ¿Cómo se instala? — instrucciones claras de instalación.
\n