Cómo comentar en PHP

Información del autor

Un comentario es un tipo de anotación que puede utilizarse para aclarar el propósito o la intención de un segmento de código. Cuando usas PHP tienes varias opciones para elegir, las cuales se desprenden de los viejos lenguajes populares, que contaban con dos alternativas para hacer comentarios de una sola línea y también comentarios de varias líneas estilo C. Puedes usar comentarios para evitar que se ejecuten ciertas partes del código o incluso usarlos para crear documentación.

Parte 1

Parte 1 de 2:
Estilos

1
Utiliza comentarios de una sola línea para hacer comentarios breves. Si necesitas dejar un comentario breve, puedes usar el código para comentarios de una línea. El comentario solo durará hasta el final de la línea o el final del bloque de código. Estos comentarios solo funcionan entre etiquetas de PHP y se leerán si los colocas en HTML.^{[1]
X
Fuente de investigación}
```
 <?php
 
 // Esta es la forma estándar (C++) de crear un comentario de una sola línea
 
# También puedes usar el estilo Unix para crear un comentario de una sola línea
 
 ?>
```
2
Utiliza comentarios de varias líneas para escribir comentarios largos o probar el código. Los comentarios de varias líneas son útiles para escribir explicaciones largas o para evitar que se procese un segmento de código. Lee la sección "Usos" más abajo para ver algunos consejos sobre los distintos usos que tienen los comentarios de varias líneas.^{[2]
X
Fuente de investigación}
```
 <?php
 
/* Esta es la forma en la que puedes darle formato
a un comentario de varias líneas. Todo lo que escribas
hasta la etiqueta de cierre se incluirá
en el comentario. */

/* Algunas personas prefieren incluir
* marcadores adicionales al principio
* de cada línea. Esto puede ayudar a mejorar la legibilidad
* de comentarios extensos, aunque en realidad no es necesario hacerlo.
*/

 ?>
```

Parte 2

Parte 2 de 2:
Usos

1
Utiliza comentarios para dejar notas acerca de cómo funciona el código. No es necesario hacerlo con cada línea de código, ya que un buen código debe ser fácilmente entendible entre los programadores. Esto es útil si el código realiza funciones poco habituales o no tan evidentes.^{[3]
X
Fuente de investigación}
```
// Generar solicitud de CURL
$session = curl_init($request);
// Decirle a CURL que use HTTP POST
curl_setopt ($session, CURLOPT_POST, true);
```
2
Deja comentarios para recordar lo que estabas haciendo. Cada vez que estés trabajando en tus propios proyectos, puedes usar comentarios para ayudarte a recordar dónde los dejaste. Deja comentarios en partes del código que no estén funcionando correctamente o que todavía no hayas terminado.
```
// Es necesario revisar la salida antes de continuar
echo "¡Hola mundo!";
```
3
Agrega comentarios en código que vayas a compartir. Si planeas colaborar con otras personas o tienes la intención de crear código abierto, los comentarios pueden ayudar a los demás a descubrir cómo funciona tu código y cuáles son los mejores lugares para hacer mejoras.^{[4]
X
Fuente de investigación}
```
/* ¿Existe alguna forma más eficiente de hacer esto? */
Género:
<input type="radio" name="gender"
<?php if (isset($gender) && $gender=="female") echo "checked";?>
value="female">Femenino
<input type="radio" name="gender"
<?php if (isset($gender) && $gender=="male") echo "checked";?>
value="male">Masculino
```
4
Utiliza comentarios para evitar que se ejecuten bloques de código específicos. Esto es útil si vas a probar algo y necesitas evitar que se ejecute cierta parte del código. Todo lo que se encuentre dentro de las etiquetas de comentarios se ignorará cuando se cargue la página.
```
 <?php
 
echo "¡/*Hola*/  mundo!";
 
 /* La palabra "Hola" no se mostrará
 cuando el código anterior se ejecute */
 
 ?>
```
5
Ten cuidado cuando vayas a comentar bloques extensos de código. La función de comentar finalizará al encontrar la primera etiqueta de cierre, o sea que si ya había un comentario de varias líneas dentro del código que comentaste, el comentario llegará solamente hasta el final del primer comentario anidado.
```
 <?php
 
 /* 
echo "¡Hola mundo!"; /* Este comentario estropeará tu código */
*/

 ?>
```
```
 <?php
 
 /* 
echo "¡Hola mundo!"; // Este comentario funcionará bien
*/

 ?>
```
6
Utiliza los comentarios para crear una pseudodocumentación. Puedes usar un formato creativo de código para crear documentación en tu código y para tu código. Esto puede ser útil en proyectos de desarrollo de código abierto.
```
 <?php
 
 //=============
 // ENCABEZADO
 //=============
 
 //-------------
 // Subencabezado
 //-------------
 
 /* Título de la sección */
 
# Aquí puede ir la documentación
# Aquí puede ir la segunda parte
 
 /*
 * Utiliza este comentario para explicar algo
 * que requeriría de varias líneas
 * o incluso varios párrafos para explicarlo
 */
 
 ?>
```

Consejos

Los comentarios en HTML y en PHP son diferentes, por lo tanto cuando vayas a desarrollar scripts (combinación de código HTML y PHP), ten cuidado de no mezclar los comentarios.
Por ejemplo, en el código que aparece a continuación, hay un documento de HTML, pero de todas formas se ejecuta código PHP. Si colocas un comentario en HTML dentro de las etiquetas de PHP, podría producirse un error.
-