Documentación de programas en Java. Uso de comentarios en Java

Los comentarios en Java y en cualquier lenguaje de programación son una herramienta que sirve para apoyar la documentación de los programas que desarrollamos y así facilitar su posterior comprensión por parte de alguna otra persona que comprenda algo de Java o el lenguaje en particular. Los comentarios, son líneas de código, que no son tenidas en cuenta por el compilador en el momento de ejecutar nuestra aplicación (es como si no estuviesen allí), por lo tanto no están sujetas a restricciones de sintaxis ni nada similar y podremos escribir cualquier cosa en éstas. El uso principal de las líneas de comentario en Java, es dar orden al código y hacerlo más comprensible, en especial cuando serán terceros los que verán y deberán entender nuestro programa (como dije anteriormente). Por ejemplo es muy común usar las líneas de comentarios, para dar una breve explicación de cómo funciona cierta parte de un código, lo cual permite identificar todo con mayor rapidez.

Vamos entonces a ver cómo hacer comentarios en Java y las características de estos. Existen tres tipos de comentarios en Java, así que veamos cada uno en detalle:

Comentarios en Java de una sola línea:

Pueden ser colocados en cualquier parte de nuestro código en Java y comienzan por un doble slash "//", al colocar el doble slash en cualquier línea de código, todo lo que haya de ahí en adelante en dicha línea será tomado como comentario, ten en cuenta que el doble slash solo convierte en comentario al texto que haya justo después de éstos y que pertenezca a su misma línea, las líneas de abajo de este, no se verán afectadas, tal como es de esperarse, el doble slash "//", solo afecta una línea desde el lugar donde se colocan.

Ejemplo comentarios en Java de una sola línea:

//Declaración del método principal public static void main(String args[]) //Aquí también se puede comentar { // Esta línea no se ejecuta ----> for(int i = 0; i <= 0; i++) //Aquí hay otro comentario System.out.print("Hola"); //Esta línea mostrará Hola en pantalla }

Comentarios en Java de múltiples líneas:

Los comentarios multi-línea en Java tal como el nombre lo indica nos permiten comentar varias líneas de nuestro código Java de manera mucho más sencilla en vez de esta añadiendo doble slash "//" a cada línea. Estos comentarios van cerrados entre "/*" y "*/", es decir comienzan donde se ponga "/*" y terminan donde esté el "*/". Estos comentarios funcionan de manera similar a los comentarios de una sola línea, pero deben tener un comienzo y un final. A diferencia de los comentarios de una sola línea, al poner el símbolo "/*" todo el código que haya tanto en la misma línea, como en las línea posteriores de este se convertirán en comentarios hasta que pongamos el "*/", de manera que si iniciamos un comentario de múltiples líneas, debemos cerrarlo, tal como sucede con las llaves o los corchetes en Java.

Ejemplo de comentario en Java de múltiples líneas

// Declaración del método principal public static void main(String args[]) { /* Esta línea no se ejecuta ---- for(int i = 0; i <= 0; i++) Esto aun sigue siendo un comentario System.out.print("Hola"); //Este es otro comentario */ System.out.print("Fin de comentarios"); }

Comentarios de documentación en Java (Javadoc):

Los comentarios de documentación, también conocidos como Javadoc, son de especial utilidad al momento de documentar no sólo el código fuente, sino el proyecto como tal. Por medio de herramientas externas, podremos generar de forma automática la documentación de un proyecto Java, a partir de estos comentarios de documentación o Javadocs.

Estos comentarios van cerrados entre "/**" y "*/", es decir comienzan donde se ponga "/**" y terminan donde esté el "*/". Nótese que los comentarios de documentación, a diferencia de los comentarios de múltiples líneas, inician con "/**" (doble asterisco) en lugar de "/*" (un solo asterisco). Adicionalmente, se recomienda que cada línea que compone el bloque de comentarios inicie con "*".

Estos comentarios además requieren de algunos "componentes" para indicar los componentes del código fuente, tales como parámetros, tipos de retorno, entre otros. Estos "componentes" se normalmente se preceden por un @, por ejemplo para indicar un parámetro de una función de usa @param, o para indicar detalles sobre el retorno se usa @return. Veamos un ejemplo:

Ejemplo de comentario de documentación en Java (Javadoc)

/** * Este método se encarga de iniciar la ejecución del programar * Éste es el método principal del proyecto * @param args[] es un arreglo con los parámetros que el reciba por consola * @return void */ public static void main(String args[]) { String saludo = mostrarSaludo("Juan"); } /** * Este método se encarga mostrar un saludo al usuario * @author JuanDMeGon * @param nombre es una cadena de texto con el nombre a usar * @return El mensaje usado para el saludo */ public static String mostrarSaludo(String nombre) { String mensaje = "Hola " + nombre; System.out.print(mensaje); return mensaje; }

Muy bien, eso es todo para ésta sección, como habrás visto es bastante sencillo todo y no debería dar problemas. De igual forma si tienes alguna pregunta y/o problema puedes plantearlo en la sección de comentarios. Si todo ha ido bien, podremos continuar con nuestro curso de Java y ver ahora cómo crear un programa en Java Básico y continuar con nuestro aprendizaje.

La última actualización de este artículo fue hace 5 años

Foto de JuanDMeGon

Juan David Meza González

JuanDMeGon

Magister, Ingeniero, Desarrollador
Web & Instructor

¡Listo!

En breve recibirás un mensaje de confirmación. Verifica, por si acaso, la carpeta de correo no deseado.

...

Si te parece bien, te enviaré de vez en cuando, mensajes de interés sobre los temas que se tratan en el sitio.

Tu dirección de correo electrónico será almacenada con un interés según el artículo en el que te encuentres.

Por supuesto, puedes cancelar tu suscripción en cualquier momento.