Porqué hay que documentar

En Java, la documentación del código es fundamental. Resulta evidente en cuanto se consulta la documentación de las clases que proporciona en los paquetes que distribuye Oracle. Toda la documentación se ha generado utilizando una herramienta, llamada javadoc. También se podrá hacer lo mismo con todos los programas.

Es muy recomendable (casi obligatorio) que el programador documente el funcionamiento de las clases dentro del propio código. A partir de unos comentarios especiales, llamados comentarios de documentación, con la herramienta javadoc se genera un conjunto de páginas en HTML, por las que se puede navegar utilizando cualquier navegador Web.

Un comentario de documentación está delimitado por una marca de comienzo (/**) y una marca de terminación (*/).  Entre estos delimitadores se pueden encontrar dos partes: una de descripción y otra parte con cero o más etiquetas de documentación. Por ejemplo:

/**
* Esta es la parte de la descripción donde se
* comenta lo que venga a continuación
*
* @param Uso de la etiqueta y comentario
*/

En este ejemplo se puede ver la estructura normal que uno se puede encontrar en un comentario de documentación. Éste empieza con el delimitador de comentario de documentación (/**) en una línea. El resto del comentario empieza siempre cada línea con un carácter asterisco. Estos asteriscos, al principio de la línea desaparecen cuando se generan las páginas HTML a partir de esta documentación. Los entornos de programación ayudan a generar este tipo de comentarios especiales, de forma que los programadores y programadoras no tengamos que preocuparnos por el tipo de formato.

La última línea termina con el delimitador de fin de comentario de documentación (*/).

Recuerda que un comentario de documentación tiene dos partes bien diferenciadas:

  1. En la primera parte va un texto en el que el programador escribe el comentario sobre la clase, atributo, constructor o método que venga a continuación; puede poner todo el texto que desee. Además, puede incluir etiquetas propias del lenguaje HTML que se mantendrán en la versión final, de manera que las interprete posteriormente el navegador Web.
  2. En la segunda parte, se pone la lista de etiquetas de documentación con un cierto texto que aparecerá después en apartados específicos de la documentación. Estas etiquetas tienen un significado especial que permite darles un formato propio en la documentación.
Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s