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

phpdocumentor download windows

Question

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

¿Cuál es el propósito de comentar así?

/** 
*   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!
*/

Answer 1

Creo que es principalmente 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 forma parte de un comentario, incluso si no puede ver el principio y el final.

Answer 2

El comentario de doble asterisco es usado 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 de un solo asterisco se tratarán como // comentarios.

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

Answer 3

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

Se utiliza para documentar funciones de 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 dedicar a mirar sus antiguas declaraciones de funciones. Aptana y Zend Studio tienen esta característica, probablemente otras también.

También puede usarlo en combinación con Reflection 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 "Registro Activo".

Answer 4

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

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

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

Answer 5

Legibilidad.

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

Answer 6

Si utiliza 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 está dentro del bloque se vuelve naranja, lo que dificulta la lectura del código.

Si en cambio lo comenta con / ** ... * /, entonces todo cambia 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 permanece muy legible.

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