Comentarios en Java: de una línea, de varias líneas y Javadoc

Para qué sirven los comentarios

Un comentario es texto en tu código fuente que el compilador de Java ignora por completo. Nunca forma parte del programa en ejecución: existe únicamente para las personas que leen el código. Usas los comentarios para explicar por qué algo se hace de cierta manera, para dejar recordatorios o para desactivar código temporalmente sin borrarlo.

Java tiene tres tipos de comentarios: de una línea (//), de bloque de varias líneas (/* */) y comentarios de documentación Javadoc (/** */). Todos cumplen la misma función básica —ser ignorados en tiempo de compilación—, pero recurres a cada uno en situaciones distintas.

Comentarios de una línea

Dos barras inclinadas (//) inician un comentario que se extiende hasta el final de la línea actual. El compilador omite todo desde el // hasta el salto de línea.

public class Main {
    public static void main(String[] args) {
        // Imprime un saludo en la consola
        System.out.println("Hello, Java!");

        int score = 90; // un comentario también puede ir después del código
        System.out.println(score);
    }
}

Fíjate en que el segundo comentario comparte línea con código real. Todo lo que va antes del // sigue ejecutándose; solo se ignora la parte posterior. Este es el estilo de comentario más común para notas cortas.

Comentarios de bloque de varias líneas

Cuando tu nota abarca varias líneas, un comentario de bloque es más limpio que anteponer // a cada línea. Un comentario de bloque empieza con /* y termina con */. Todo lo que hay entre ambos —sin importar cuántas líneas— se ignora.

public class Main {
    public static void main(String[] args) {
        /*
         * Este programa muestra un comentario de bloque.
         * Los asteriscos al inicio de cada línea son solo una
         * convención para mejorar la legibilidad: no son obligatorios.
         */
        System.out.println("Block comments are handy.");
    }
}

Los caracteres * alineados a lo largo del borde izquierdo son una convención de estilo, no una regla. Las únicas partes que realmente importan son el /* de apertura y el */ de cierre.

Comentar código

Los comentarios son la forma estándar de desactivar código mientras experimentas, sin borrarlo. Usa // para una sola línea, o un comentario de bloque para desactivar varias líneas a la vez.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Ejecútalo y verás que solo se imprimen las dos líneas "runs". Las llamadas a println comentadas son invisibles para el compilador.

Un error frecuente: los comentarios de bloque no se anidan. El primer */ cierra el comentario, sin importar cuántos /* lo precedan. Por eso no puedes envolver un bloque /* ... */ dentro de otro bloque /* ... */: el */ interno termina todo y el resto se convierte en un error de sintaxis. Si necesitas desactivar una región que ya contiene comentarios de bloque, usa // en cada línea (la mayoría de los editores lo hacen con un solo atajo de teclado).

Comentarios de documentación Javadoc

Un comentario Javadoc se parece a un comentario de bloque, pero empieza con /** —dos asteriscos—. Está pensado para documentar una clase, un método o un campo, y se coloca justo encima de aquello que describe. La herramienta javadoc los convierte en documentación HTML navegable de la API, y los IDEs los muestran como información emergente al pasar el cursor.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

Las etiquetas @param, @return y @throws son campos estructurados que la herramienta entiende. Para el compilador esto sigue siendo solo un comentario ignorado: su valor está por completo en la documentación que produce y en las sugerencias que el IDE ofrece a otros desarrolladores (y a ti mismo, seis meses después).

Buenos comentarios frente al ruido

Un comentario debería explicar algo que el código no puede decir por sí solo. Los comentarios que se limitan a repetir lo que hace el código añaden desorden y tienden a quedar desactualizados a medida que el código cambia.

// Mal: solo repite lo que el código hace de forma evidente
int i = i + 1; // suma uno a i

// Mejor: explica el motivo, que el código no puede mostrar
retries++; // espera y reintenta; la API está limitada a 5 req/seg

Procura que el código sea legible mediante nombres claros y una buena estructura, y reserva los comentarios para el porqué: la intención, las concesiones, los casos límite y los enlaces al contexto. Si te encuentras escribiendo un comentario para explicar una línea confusa, eso suele ser una señal de que conviene renombrar una variable o extraer un método en su lugar.

Siguiente: Variables

Ahora que sabes anotar tu código, el siguiente bloque de construcción es almacenar datos en él. La siguiente página trata las variables: cómo declararlas, los tipos que contienen y las reglas que Java impone por ser de tipado estático.