¿Cómo hacer comentarios en Java?

Icono play
Java
Comentarios

La mejor forma de que el código de nuestro programa sea accesible es desarrollarlo con nombres de variables, métodos y clases autoexplicativos que permitan interpretar su propósito o resultado, sin agregar comentarios.

Sin embargo, muchas veces los nombres de esos componentes no pueden explicar por sí mismos su funcionalidad aunque lo intentemos, es aquí donde utilizamos comentarios como referencia para que consultas a futuro, puedan ser resueltas.

Un comentario es un bloque de texto que usaremos de forma medida, el mismo será ignorado por el compilador, no está sujeto a restricciones de sintaxis y no cambiará el funcionamiento de nuestra aplicación.

No debemos abusar de su uso y solo los emplearemos si realmente son útiles para tener un código limpio, fácil de mantener y entendible. Cada lenguaje tiene su propia sintaxis.

El uso principal de las líneas de comentario en Java, es dar orden al código y hacerlo más comprensible, es buena costumbre tabularlos todos a la misma posición.

Tipos de comentarios en Java

Java dispone de tres tipos de comentarios, dos para notas regulares en el código fuente y uno para documentación:

Comentarios de línea:

Para comentar una sola línea se utiliza la doble diagonal // o con /* */.
El comentario se inicia cuando se encuentra la doble diagonal y continua hasta el final de la línea.

// Este es un comentario de una sola línea
/* Este también es un comentario de una sola línea*/

Comentarios de bloque

Un comentario de bloque se inicia con /* y se finaliza con */, la sintaxis es la misma que el comentario de una sola línea.

/*

Este es un ejemplo de un comentario en bloque.
Aquí puedes especificar con más detalle lo que realiza tu código

*/

Comentarios para documentación:

Este tipo de comentarios es similar al de bloque, admite varias líneas y con palabras específicas le indica a Java que debe generar documentación, se escribe entre /** */

 /**
 
* aquí van las palabras reservadas para documentar
* las mismas deben ir precedidas por un @ y al principio del componente que se quiere * documentar, normalmente clases

*/

Para realizar la documentación, existe Javadoc que es una utilidad de Java que generará de forma automática un archivo en formato HTML a partir de código fuente java.

Javadoc identificará todas las clases, métodos, parámetros y retornos junto con la información y especificaciones que decidamos incluir en la documentación de nuestra API.

En cada clase se deberá incluir una breve descripción.

En cada método se describirá su objeto y funcionalidades, así como sus parámetros y retornos.

Para documentar se utilizan determinadas palabras reservadas (tags), precedidas de un “@”. Si no existe al menos una línea que comience con @ no se reconocerá el comentario para la documentación de la clase. Se pueden combinar varias etiquetas para documentar.

Algunas palabras reservadas para documentar un proyecto en Java:

  • @author: indica el autor de la clase o método.
  • {@link}: incluye un enlace a otra sección de la documentación, método o clase.
  • @param: documenta un parámetro de un método.
  • @return: documenta el valor de retorno de un método.
  • @see: incluye un enlace con documentación adicional en la sección final de la documentación.
¿Todavía no te has apuntado a nuestro Bootcamp?
Tenemos muchos cursos para ofrecerte y ¡TOTALMENTE GRATIS! Estos son algunos de ellos: