He (finalmente) estado leyendo sobre los estándares de codificación PEAR (php).¿Cuál es el propósito de los asteriscos adicionales en los comentarios de php?
Cuál es el propósito de hacer comentarios como éste:
/**
* Here is my comment
* I Wrote this in a haiku
* But why put the stars?
*/
En oposición a esto:
/*
Here is a comment
No haiku or
anything special, but it still works!
*/
El documento /** stuff */ también se conoce como DocBlock notación.
Se utiliza para documentar las 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 esta para realizar su función de Código de Insight, una herramienta muy potente que reduce el tiempo que tiene que pasar mirando tus antiguas declaraciones de funciones. Aptana y Zend Studio tienen esta característica, probablemente también otras.
También puede usarlo en combinación con Reflection para hacer algún tipo de AOP, haciendo la inspección del tiempo de ejecución del DocBlock sobre sus declaraciones. De hecho, Doctrine lo usa para construir un object attribute map para su implementación de "Registro activo".
legibilidad.
Claramente resalta la sección comentada para las personas que leen el código.
Eso es lo que pensé ... ¿Así que es estrictamente para la legibilidad? No hay otros beneficios? –
si está utilizando un editor que no resalta el contexto, ayuda a aclarar/identificar bloques de comentarios más largos – Dave
Esto no es del todo cierto. TÉCNICAMENTE es una formalidad utilizar el asterisco del doblaje. Pero los sistemas de documentación, como phpdoc, dependen de ello. – dcbarans
Creo que es principalmente por apariencia/legibilidad. Imagine que tiene 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.
Estoy de acuerdo con ajon y Quentin. Principalmente es legibilidad. Sin embargo, hay una cosa más.
Hay generadores de documentación automáticos (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:
Sí, encontré esto cuando busqué doxygen, así que supuse que * había * un poco más –
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 de un solo asterisco se tratarán como // comentarios.
Ver PHPDoc http://www.phpdoc.org/docs/latest/guides/types.html
Si utiliza la excelente jEdit editor de texto gratuito para la edición de su PHP que pone de relieve el código en diferentes colores para mostrar lo que es un verbo, lo que es una variable etc.
Si usted comenta un bloque con/* ... */todo dentro del bloque se vuelve naranja, lo que dificulta leer el código.
Si en lugar de comentarlo/** ... */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.
PS. Si usa el Bloc de notas o similar para editar su código PHP, le sugiero encarecidamente 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.
No entiendo los votos cercanos. Es una pregunta legítima. Hay una verdadera razón para comentar de esta manera. – bstpierre