:::: MENÚ ::::

PHPdoc, el estándar de comentarios

Llevo tiempo escribiendo y mirando código en distintos lugares como WordPress, Drupal, scripts o snippets y me había fijado que hay como una especie de estándar para los propios comentarios en el código.

Pues no es una conjetura, es cierto, hay un estándar para los comentarios llamado PHPdoc (inspirado en javadoc), pero, ¿Para qué nos sirve?.

(wikipedia – PHPdoc)

  • Mejorar la compresión y el uso de los comentarios del código, mediante un estándar.
  • Leas en el lenguaje de programación que sea, es un estándar en todos ellos (con ciertas variaciones).
  • Permite que los generadores de documentos externos como phpDocumentor puedan crear la documentación API en buen formato y fácil de entender.
  • Permite que algunos IDEs interpreten los tipos de variables y otras ambigüedades en el lenguaje de programación.

Su uso

Los bloques de comentarios se denominan DocBlock y se suelen incluir aunque no obligatoriamente antes de namespace, require{_once}, include{_once}, class, interface, trait, function (incluido methods), property, constant y variables (locales y globales).

El DocBlock comienzan con /** (doble asterisco) y terminan */, y en cada línea hay que añadir *, un ejemplo completo sería:

/**
 * Esto es una descripción corta del DocBlock, que sería como un título.
 *
 * Esto es una descripción larga del DocBlock. Este texto puede contener
 * múltiples líneas y como máximo 80 columnas. Puede incluir distinta
 * información como {inline @tags} para enriquecer la descripción, un listado
 * como el siguiente, entre otras muchas cosas.
 * 
 * Lista de ejempo:
 * 	+ Elemento 1
 * 	+ Elemento 2
 *
 * Después de una descripción larga (que es opcional), viene la lista de @tags
 * (opcional) que nos da información sobre el código que viene a continuación,
 * por ejemplo:
 *
 * @author	Nombre y apellido <dirección de email>
 * @version	0.1
 *
 * @param	int		$foo	Una descripción del parámetro de un function/method
 * @param	string	$bar	Otro descripción
 *
 * @return	array|bool	Un retorno que puede devolver un array o un bolean
 */
function( $foo, $bar ) { [...] }

Las partes

El DocBlock se divide en 3 partes y son:

  • Short Description (linea 2): Corresponde a un pequeña descripción normalmente no superior a 80 columnas. Se puede decir que se podría denominar el título. Es obligada su aparición.
  • Long Description (lineas 4 a 15): Una descripción completa de lo que puede hacer el código siguiente incluyendo {inline @tag}. Puede contener el número de párrafos que quieras, sin límites. Cear una nueva linea cada 80 columnas.
  • @tags (lineas 17 a 23): Etiquetas que representan información específica como el autor (@author), los parámetros con su tipo y nombre de una función/método (@param), el tipo de retorno de una función/método (@return), entre una gran lista de tipos y @tags.

Recomendaciones

No es obligatorio pero sí importante crear una nueva linea cada 80 columnas, para facilitar la lectura a distintos usuarios y medios.

Si sólo vas a hacer una pequeña anotación puede usar los otros tipos de comentarios // y /* [...] */ e incluso, si deseas usar un DocBlock para esa anotación, lo puedes hacer en una sola linea, por ejemplo:

/** Usando el Short Description para una "anotación" del include_once */
include_once( 'foo.php' ); 

Los IDEs que pueden procesar PHPdoc ignorarán todos los comentarios que no estén declarados como un DocBlock.

Share on Facebook0Tweet about this on TwitterShare on Google+0Share on LinkedIn2Share on Tumblr0Pin on Pinterest0Email this to someone