¿Cuál es el propósito de los asteriscos adicionales en los comentarios de php?

3 minutos de lectura

(Finalmente) he estado leyendo sobre los estándares de codificación PEAR (php).

Cual es el proposito de comentar asi:

/** 
*   Here is my comment
*   I Wrote this in a haiku
*   But why put the stars?
*/

A diferencia de esto:

/* 
   Here is a comment
   No haiku or 
   anything special, but it still works!
*/

  • No entiendo los votos cerrados. Es una pregunta legítima. Hay una verdadera razón para comentar de esta manera.

    – bstpierre

    2 oct 2012 a las 11:57

Avatar de usuario de Jack
Jacobo

Él /** stuff */ El documento también se conoce como DocBlock notación.

Se utiliza para documentar funciones PHP, clases, etc.

/** 
* A test function
*
* @param  foo $bar
* @return baz
*/
function test(foo $bar) { return new baz; }

Algunos editores hacen un buen uso de esto para realizar su función Code Insight, una herramienta muy poderosa que reduce el tiempo que tiene que pasar mirando las declaraciones de funciones anteriores. Aptana y Zend Studio tienen esta característica, probablemente otras también.

También puedes usarlo en combinación con Reflexión para hacer algún tipo de AOP, haciendo una inspección en tiempo de ejecución del DocBlock sobre sus declaraciones. De hecho, Doctrine lo usa para construir un mapa de atributos de objeto para su implementación de “Active Record”.

avatar de usuario de dcbarans
Dcbarans

El comentario de doble asterisco se utiliza en algún momento por ciertos sistemas de documentación. El sistema de documentación procesará el bloque y buscará ciertas palabras clave como @author o @var.

Los comentarios con un solo asterisco se tratarán como // comentarios.

Ver PhpDoc
http://www.phpdoc.org/docs/latest/guides/types.html

Avatar de usuario de Victor Ronin
Víctor Ronín

Estoy de acuerdo con ajon y Quentin. Principalmente es la legibilidad. Sin embargo, hay una cosa más.

Hay generadores automáticos de documentación (como doxygen).

Requieren un formato de comentario particular para incluir estos comentarios en la documentación. Creo que este estilo de comentario se usa exactamente para este propósito (consulte la siguiente página de documentación de doxygen: http://www.doxygen.nl/manual/docblocks.html)

  • Sí, encontré esto cuando buscaba doxygen, así que supuse que había fue un poco más a eso

    – d-_-b

    1 oct 2012 a las 16:52

Legibilidad.

Resalta claramente la sección comentada para las personas que leen el código.

Creo que es principalmente solo por apariencia/legibilidad. Imagina que tienes una sección de comentarios muy larga que se extiende más allá de una pantalla. Luego, ver esos asteriscos le permite saber que es parte de un comentario, incluso si no puede ver el principio y el final.

avatar de usuario de user2605793
usuario2605793

Si usa el excelente editor de texto gratuito jEdit para editar su PHP, resalta el código en diferentes colores para mostrar qué es un verbo, qué es una variable, etc.

Si comenta un bloque con /* … */, todo lo que hay dentro del bloque se vuelve naranja, lo que dificulta la lectura del código.

Si, en cambio, lo comenta con /** … */, cambia todo en el bloque a un conjunto diferente de colores que aún resaltan las diferentes partes del código, lo que significa que el código sigue siendo muy legible.

PD. Si usa el Bloc de notas o similar para editar su código PHP, le sugiero que obtenga jEdit. Le ahorrará una gran cantidad de tiempo y frustración. Cosas como indicar automáticamente el inicio y el final de { } , ( ) etc.

¿Ha sido útil esta solución?