Comprender los comentarios en PHP

Los comentarios son notas que dejas dentro del código fuente y que PHP ignora al ejecutar el programa. Existen únicamente para las personas — para explicar por qué un fragmento de código hace lo que hace, dejar recordatorios o deshabilitar código temporalmente durante la depuración. Esta guía cubre todos los estilos de comentarios que admite PHP, cuándo usar cada uno y las prácticas que mantienen los comentarios útiles en lugar de ruido.

Este capítulo asume que ya sabes escribir PHP básico. Si no es así, comienza primero con los capítulos de Sintaxis de PHP y Variables en PHP.

¿Qué son los comentarios en PHP?

Un comentario es texto en tu código que el motor de PHP no ejecuta. Cuando PHP analiza un archivo, omite los comentarios por completo — nunca afectan la salida, el rendimiento ni el comportamiento. Sirven como documentación para quien lea el código después, incluido tu yo futuro.

PHP admite tres estilos de comentarios, que se dividen en dos grupos:

• Comentarios de una línea, escritos con // o #.
• Comentarios de varias líneas (bloque), escritos con /* ... */.

PHP hereda los estilos // y /* */ de C y Java, y el estilo # de los scripts de shell y Perl — así que, sin importar de qué lenguaje vengas, uno de estos te resultará familiar.

Comentarios de una línea

Un comentario de una línea hace que PHP ignore el resto de la línea actual. PHP ofrece dos marcadores intercambiables para esto: // (estilo C) y # (estilo shell). Se comportan de forma idéntica — elige uno y mantén la coherencia dentro de un proyecto.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

El comentario termina en el salto de línea, por lo que las instrucciones echo siguen ejecutándose. El script anterior imprime Hello, world! Goodbye! Done.

Comentarios de varias líneas

Un comentario de varias líneas comienza con /* y termina con */. Todo lo que hay entre esos marcadores se ignora, incluso a lo largo de muchas líneas. Úsalo para explicaciones más largas o para comentar un bloque de código de una sola vez.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

Las dos instrucciones echo imprimen Visible output — still works; todo lo que está dentro de /* ... */ se omite.

Precaución — los comentarios de bloque no se anidan. PHP detiene el comentario en el primer */ que encuentra. Si envuelves código que ya contiene un comentario /* ... */, el bloque exterior termina antes de tiempo y el */ sobrante provoca un error de análisis. Para deshabilitar un fragmento de código que ya tiene comentarios de bloque, usa // o # en cada línea en su lugar.

¿Por qué usar comentarios en PHP?

Los comentarios en PHP son una herramienta importante para los desarrolladores, ya que ayudan a que el código sea más fácil de entender y mantener. Al añadir comentarios a tu código, puedes explicar el propósito de líneas específicas o proporcionar información adicional sobre el código. Esto facilita que otros desarrolladores comprendan y mantengan tu código, y también te ayuda a recordar qué hace tu código si vuelves a él más adelante.

Cómo usar los comentarios en PHP

Para añadir un comentario a tu código PHP, simplemente comienza la línea con dos barras inclinadas hacia adelante (para comentarios de una línea) o con una barra inclinada y un asterisco (para comentarios de varias líneas). Es importante elegir el tipo de comentario adecuado según el tamaño y la complejidad del código que estás comentando.

También es importante asegurarte de que tus comentarios sean claros y concisos, y de que proporcionen información significativa sobre el código. Evita usar comentarios para simplemente repetir el código o para decir lo obvio. En cambio, céntrate en proporcionar información que no sea inmediatamente evidente a partir del código.

Comentar código durante la depuración

Uno de los usos más prácticos de los comentarios es deshabilitar código temporalmente sin eliminarlo. Antepón // o # a una línea, o envuelve varias líneas en /* ... */, para sacarlas del programa:

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Recuerda la regla de no anidamiento anterior: si el código que quieres deshabilitar ya contiene un bloque /* */, coméntalo línea por línea con // en su lugar.

Comentarios de documentación (PHPDoc)

Más allá de los comentarios simples, el ecosistema PHP tiene una convención de documentación llamada PHPDoc. Es un comentario de bloque que comienza con /** (dos asteriscos) y usa etiquetas @ para describir funciones, parámetros y valores de retorno. Los IDEs y herramientas como phpDocumentor los leen para proporcionar autocompletado y generar documentación de API.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

PHPDoc es técnicamente solo un comentario /* */ normal para el motor de PHP — no tiene efecto en tiempo de ejecución — pero seguir la convención hace que tus funciones sean mucho más fáciles de entender para los editores y los compañeros de equipo. Lo verás ampliamente en el capítulo de Funciones de PHP.

Buenas prácticas para los comentarios en PHP

Aquí hay algunas buenas prácticas a seguir al usar comentarios en PHP:

• Usa un lenguaje claro y conciso en tus comentarios
• Evita repetir el código en los comentarios — explica el por qué, no el qué
• Céntrate en proporcionar información que no sea inmediatamente evidente a partir del código
• Usa niveles de detalle apropiados en tus comentarios
• Mantén tus comentarios actualizados a medida que evoluciona tu código — un comentario obsoleto es peor que ninguno
• Prefiere nombres de variables y funciones autoexplicativos antes que comentarios que expliquen los poco claros

Conclusión

Los comentarios en PHP son una herramienta esencial para los desarrolladores, ya que les permiten hacer su código más fácil de entender y mantener. PHP ofrece tres sintaxis — // y # para líneas individuales, y /* ... */ para bloques — además de la convención PHPDoc para documentar funciones. Siguiendo las buenas prácticas descritas en este artículo, puedes aprovechar al máximo los comentarios en PHP y asegurarte de que tu código esté bien documentado y sea fácil de entender para otros desarrolladores.

Para continuar aprendiendo, pasa a Variables en PHP y Operadores en PHP.

Práctica