Comentarios en Java

Para poner comentarios en nuestro código fuente java tenemos tres opciones:

Una línea de comentario que empiece por //

// Esto es un comentario
System.out.println ("Hola mundo");

Varias líneas encerradas entre /* y */

/* Todo esto
   también es un
   comentario */
System.out.println ("Hola mundo");

Finalmente, podemos hacer varias líneas de comentario entre /** y */

/** Todo esto
   también es un
   comentario */
public void unMedodo (int unParametro) {
   ...
}

La diferencia entre el comentario que empieza por /** y el que empieza por /* es que el primero sale en la documentación generada por javadoc y en la mayoría de herramientas que hacen documentación a partir del código. El comentario que empieza por /* no sale en la documentación.

Hay unos detalles, sin embargo, que conviene tener en cuenta para comentarios que van a salir en la documentación. Conviene poner uno de estos comentarios delante de cada clase, cada método y cada atributo, de esta forma, en la documentación aparecerán convenientemente documentados las clases, métodos y atributos. Lo siguiente puede ser un ejemplo.

/**
 Montones de funciones matemáticas.
 Realiza operaciones trigonométricas, ecuaciones diferenciales
 e integrales */
 public class Matematicas {
    
    /** PI.
        Pues eso, PI=3.14 y pico */
    public static final double PI = 3.1416;

    /** Devuelve el seno del ángulo que se le pasa.
        El ángulo debe estar en radianes. */
    public double sin(double angulo) {
       ...
    }
 }

Es importante tener en cuenta que dentro de cada comentario, la primera frase -hasta el primer punto- saldrá como resumen de la clase, método o atributo. Conviene, por tanto, que esa frase tenga sentido por sí sola.

En el ejemplo, si generamos la documentación, saldrá como resumen de

• La clase Matematicas : "Montones de funciones matemáticas"
• El atributo PI : "PI"
• El método sin() : "Devuelve el seno del ángulo que se le pasa"

Si en la documentación vamos a la parte de detalle de la clase, método o atributo, veremos el resto del comentario.

En la documentación de la clase EscalaGraficaCartesiana puedes ver el resumen -que es el texto que aparece en el lista de métodos dentro de la caja- y el comentario detallado -lo que aparece en los métodos que van después de la tabla-.