AjLearning
AjLearning 0.1    





Introducción a Java - Comentarios

Curso Introducción a Java

    Anterior     Siguiente

Comentarios en el código


Algo que frecuentemente olvidamos, es el uso de comentarios en nuestros programas. Sí, esos fragmentos escritos en idioma mortal y humano, que nos podría ayudar dentro de seis meses, a entender lo que hacía la maravillosa rutina que hoy escribimos.

Java no se olvida de esos textos, y permite implementarlos de una forma que nos recuerda al C/C++, así:

// comentario hasta el fin de la línea i = i+1; // incremento la variable i
Los caracteres // (dos barras) indican el comienzo de un comentario que se extiende hasta el final de la línea. Puede estar precedido por texto de código en la misma línea.

/* Comentario que comienza y se extiende hasta indicar el fin */
Los caracteres /* indican el comienzo de un comentario, que se extiende, una o varias
líneas, completas o no, hasta llegar a los caracteres */ que indican el final del
comentario.

Contrariamente a C++, los comentarios en Java no se pueden anidar. Un código como el siguiente:

/* Esta rutina no me sirve public void Incrementa() { i=i+1; /* Incremento i */ i=i-1; } */
no compilaría normalmente, porque el primer /* (apertura de comentario)
se cerraría con el primer */

Comentarios de Documentación


Existe en Java el concepto de generar documentación del programa a partir del código fuente. Para ayudar en el proceso automático se han introducido los comentarios de documentación:

/** Comentario de documentación puede extenderse varias líneas */ public void .....
Este es un tipo de comentario propio de Java. Es el comienza con /** (una barra y dos
asteriscos). Igual que el comentario anterior, termina en */ y puede abarcar varias líneas. Su particularidad reside en que hay utilitarios que tratan a estos comentarios de forma especial, como conteniendo información para la documentación del programa,
o, por ejemplo, del método que se implementa a continuación. El programa javadoc (documentador de java), incluído en el JDK, es uno de esas aplicaciones que trata
a estos comentarios como documentación. La documentación de la librería (API) de Java se incluye en formato HTML con el JDK, y ha sido generada automáticamente con ese
documentador de código fuente. Siguiendo las ideas de Donald Knuth, la mejor documentación de un programa, es el propio código. Si estudiamos el código fuente de la librería (que también se incluye con el JDK), encontraremos estos comentarios de documentación
por doquier, siendo un ejemplo de su utilidad.

Un comentario de documentación puede contener marcas de HTML, así como marcas especiales que comienzan con @. El carácter @ es seguido por una palabra clave que identifica esa marca especial.

Algunas de las marcas especiales a usar:

@author Par indicar el autor de código
@param Describe un parámetro del método
@return Explica el valor retornado por el método
@deprecated Marca a un método o clase como obsoleta, recomendando
que no se use en los nuevos programas.
@exception Para documentar las excepciones que el código puede disparar
@see Apunta a otros temas de documentación
@throws Es un sinónimo de @exception
@version La versión del código
{@link} Genera un enlace a otra parte de la documentación. Las
llaves separan el enlace del resto del texto.


Programado por Angel J. Lopez www.ajlopez.com