7.- Comentarios.

Caso práctico

Imagen en la que se aprecia a Juan programando delante del ordenador.

Juan ha podido comprobar los avances que ha hecho María con la programación. Ya domina todos los aspectos básicos sobre sintaxis, estructura de un programa, variables y tipos de datos. Ada le acaba de comunicar que van a sumarse al proyecto dos personas más, Ana y Carlos que están haciendo las prácticas del ciclo de Desarrollo de Aplicaciones Multiplataforma en la empresa. —Al principio de cada programa indicaremos una breve descripción y el autor. En operaciones complicadas podríamos añadir un comentario les ayudará a entender mejor qué es lo que hace —indica Juan. —De acuerdo —comenta María, —y podemos ir metiendo los comentarios de la herramienta esa que me comentaste, Javadoc, para que se cree una documentación aún más completa. — ¡Ajá! —asiente Juan— pues ¡manos a la obra!

Los comentarios son muy importantes a la hora de describir qué hace un determinado programa. A lo largo de la unidad los hemos utilizado para documentar los ejemplos y mejorar la comprensión del código. Para lograr ese objetivo, es normal que cada programa comience con unas líneas de comentario que indiquen, al menos, una breve descripción del programa, el autor del mismo y la última fecha en que se ha modificado.

Todos los lenguajes de programación disponen de alguna forma de introducir comentarios en el código. En el caso de Java, nos podemos encontrar los siguientes tipos de comentarios:

Comentarios de una sola línea. Utilizaremos el delimitador // para introducir comentarios de sólo una línea.
```
// comentario de una sola línea
```
Comentarios de múltiples líneas. Para introducir este tipo de comentarios, utilizaremos una barra inclinada y un asterisco (/*), al principio del párrafo y un asterisco seguido de una barra inclinada (*/) al final del mismo.
```
/* Esto es un comentario 

de varias líneas */
```

Comentarios Javadoc. Utilizaremos los delimitadores /** y */. Al igual que con los comentarios tradicionales, el texto entre estos delimitadores será ignorado por el compilador. Este tipo de comentarios se emplean para generar documentación automática del programa. A través del programa javadoc, incluido en JavaSE , se recogen todos estos comentarios y se llevan a un documento en formato .html.

/** Comentario de documentación.

Javadoc extrae los comentarios del código y

genera un archivo html a partir de este tipo de comentarios

*/

Reflexiona

Una buena práctica de programación es añadir en la última llave que delimita cada bloque de código, un comentario indicando a qué clase o método pertenece esa llave.

Para saber más

Si quieres ir familiarizándote con la información que hay en la web de Oracle, en el siguiente enlace puedes encontrar más información sobre la herramienta Javadoc incluida en el Kit de Desarrollo de Java SE (en inglés):

Página oficial de Oracle sobre la herramienta Javadoc