Los comentarios en Java como en cualquier otro lenguaje de programación son un texto que se escribe dentro de un programa con el fin de facilitar la comprensión del mismo.

El compilador ignora los comentarios por completo, por lo que no afectan a la ejecución del programa. Su función principal es mejorar la comprensión del código, documentar decisiones de diseño y facilitar el mantenimiento de los programas a largo plazo.

Tabla de contenidos

Tipos de comentarios en Java

En Java existen tres tipos de comentarios, cada uno pensado para situaciones distintas.

Comentarios de múltiples líneas

Son los mismos comentarios que se usan en lenguajes como C.

Los comentarios de varias líneas son útiles cuando se necesita escribir explicaciones largas o dejar notas que ocupan varias líneas.

Las características de los comentarios en Java de múltiples líneas son las siguientes:

Empieza con los caracteres /* y acaba con los caracteres */.
Pueden ocupar más de una línea y pueden aparecer en cualquier lugar donde pueda aparear un espacio en blanco.
Los comentarios de múltiples líneas no pueden anidarse.

Estos comentarios permiten documentar bloques completos de código o describir lógicas complejas sin interrumpir la legibilidad del programa.

Ejemplos de comentarios de múltiples líneas:

/* Programa Ecuación de segundo grado
   Calcula las soluciones de una ecuación de segundo grado */

/* 
    Lectura de datos del cliente
    Se introduce el dni, nombre, dirección, 
    teléfono y correo electrónico
 */

Ejemplo de comentario de múltiples líneas no válido:

/* 
    Lectura de datos del cliente
    /* 
         Se introduce el dni, nombre, dirección, 
         teléfono y correo electrónico
    */
 */

Comentario no válido. Este tipo de comentarios no se pueden anidar.

Comentarios de una sola línea

Se utilizan para añadir anotaciones breves o aclaraciones rápidas dentro del código.

Las características de los comentarios en Java de una línea son las siguientes:

Comienzan con una doble barra //
Todo lo todo lo que aparece a continuación de // en esa misma línea se considera comentario.
Pueden escribirse al principio de la línea o a continuación de una instrucción.
No tienen carácter de terminación.

El comentario de una línea es ideal para describir instrucciones concretas o apuntar detalles que no requieren una explicación extensa.

Ejemplos de comentarios Java de una sola línea:

// Programa Ecuación segundo grado

// Cálculo de la nota media del curso

double precio;  // variable para almacenar el precio del producto

Comentarios de documentación Javadoc

Los comentarios Javadoc son una característica distintiva de Java diseñada para crear documentación técnica directamente a partir del código fuente. Este sistema permite describir clases, interfaces, métodos, constructores y atributos de una forma estandarizada, generando automáticamente páginas HTML claras y navegables mediante la herramienta javadoc incluida en el JDK.

A diferencia de los comentarios comunes, los comentarios Javadoc no solo explican el funcionamiento interno del código, sino que también ofrecen una descripción formal del contrato de cada componente: qué hace, qué parámetros recibe, qué devuelve y qué excepciones puede lanzar.

Las características de los comentarios de documentación son:

Comienza con /** y termina con */
Suelen incluir etiquetas estándar como @param, @return o @author
Permiten crear páginas HTML con la documentación del programa

Mediante los comentarios Javadoc es posible generar documentación en formato HTML, lo que resulta especialmente útil en proyectos grandes o librerías públicas.

Ejemplo de comentario javadoc

/**
 * Gestiona operaciones básicas con cuentas bancarias.
 *
 * Esta clase permite crear cuentas, consultar saldos y realizar operaciones de ingreso y retirada.
 *
 * @author Enrique García
 * @version 2.0
 * @since 1.0
 */
public class Cuenta {
         ............
}

Principales etiquetas javadoc

A continuación se presentan las etiquetas más utilizadas en los comentarios javadoc, junto con una breve explicación de cada una:

`@param`	Describe un parámetro de un método o constructor. Se indica el nombre del parámetro seguido de su descripción.
`@return`	Indica qué devuelve un método y en qué condiciones.
`@throws` o `@exception`	Documenta las excepciones que el método puede lanzar, junto con el motivo.
`@author`	Indica el autor o responsable del código. Se usa especialmente en librerías o proyectos colaborativos.
`@version`	Permite especificar la versión del elemento, útil para llevar un histórico.
`@since`	Indica la versión desde la cual existe ese componente.
`@deprecated`	Marca un elemento como obsoleto, proporcionando una explicación y, opcionalmente, una alternativa recomendada.
`@see`	Añade referencias cruzadas a otros elementos relacionados, mejorando la navegación.
`@code`	Permite insertar pequeños fragmentos de código en línea dentro de la descripción.
`@link`	Crea un enlace interno hacia otra clase o método.

Puedes ampliar la información sobre Javadoc en Javadoc Tool.

Buenas prácticas al escribir comentarios

Un comentario debe ser claro y directo. El comentario debe aportar valor, no confundir.
Hay que evitar repetir lo obvio. Si el código ya es evidente, el comentario no añade utilidad.
Actualizar los comentarios cuando cambie el código: Un comentario desactualizado puede ser más perjudicial que no tener ninguno.
Usar comentarios para explicar el “por qué”: El código explica el “cómo”; los comentarios deben ayudar a entender las razones detrás de una decisión.

Los comentarios bien escritos hacen que el código sea más fácil de entender, mantener y compartir. Utilizarlos adecuadamente contribuye a que cualquier proyecto en Java sea más profesional y durable.