Comentarios en Java

Los comentarios son texto que el compilador ignora. Existen para las personas que leen el código fuente. Java tiene tres tipos — de una línea, multilínea y Javadoc — cada uno con su propio propósito.

Este capítulo cubre la sintaxis de los tres estilos, cómo generar documentación HTML a partir de Javadoc y — igual de importante — cuándo vale la pena escribir un comentario y cuándo solo añade ruido. Si eres nuevo en la estructura de Java, lee primero Java Syntax.

Comentarios de una línea — //

Todo lo que va desde // hasta el final de la línea es un comentario:

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

Úsalos para notas cortas junto a una línea de código, o para deshabilitar temporalmente una línea durante la depuración.

Comentarios multilínea — /* ... */

Todo lo que se encuentra entre /* y */ se ignora, incluso si abarca varias líneas:

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

Los comentarios multilínea también pueden aparecer de forma inline:

int width = 800 /* pixels */;

No puedes anidarlos: /* outer /* inner */ */ termina en el primer */, dejando caracteres */ sueltos que no compilan. Para "comentar" un bloque que ya contiene /* … */, usa // en cada línea (tu IDE tiene un atajo para ello — normalmente Ctrl+/ / Cmd+/).

Comentarios Javadoc — /** ... */

Los comentarios Javadoc comienzan con /** (nota: dos asteriscos) y son leídos por la herramienta javadoc para generar documentación HTML:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Los comentarios Javadoc se colocan inmediatamente encima de la clase, método o campo que describen. La primera oración se convierte en la línea de resumen en la documentación generada.

Las etiquetas más útiles:

• @param name description — una por parámetro
• @return description — qué devuelve el método
• @throws ExceptionClass description — cuándo el método lanza una excepción
• @see ClassOrLink — referencia cruzada
• @since 1.5 — cuándo se añadió esta API
• @deprecated reason — desaconseja su uso posterior (el compilador también advierte)

Toda la biblioteca estándar está documentada con Javadoc; los IDEs la leen para mostrar sus tooltips.

Generación de la documentación HTML

La herramienta javadoc viene incluida con el JDK. Apúntala a tus archivos fuente (o paquetes) y genera un sitio HTML navegable:

javadoc -d docs Greeter.java

El indicador -d docs elige el directorio de salida. Abre docs/index.html en un navegador para ver las páginas generadas — el mismo diseño que obtienes en la documentación oficial de la API de Oracle, construido a partir de los comentarios encima de cada clase y método.

Cuándo comentar y cuándo no

El buen código es su propia documentación. Los comentarios que repiten lo que el código ya muestra solo añaden ruido y se desactualizan rápidamente:

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

Los comentarios justifican su lugar cuando explican el por qué, no el qué:

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

O cuando documentan una restricción no obvia:

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

Para las APIs públicas, escribe Javadoc. Para el código interno, escribe solo los comentarios que ayuden al próximo lector a tomar una decisión.

Una demostración

El compilador elimina los tres estilos de comentarios antes de generar el bytecode, por lo que tienen costo en tiempo de ejecución cero.

Qué viene después

Ahora que puedes documentar código, pasa a los bloques de construcción que describe:

• Java Variables — declaración, inicialización y ámbito.
• Java Syntax — sentencias, bloques y las reglas que el compilador aplica.
• Java Hello World — el programa mínimo donde viven tus comentarios.

Práctica