1.4 Comentarios

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-.

Los felicito por sus participaciones, y para una próxima ocasión los invito a contestar dentro de la sala de discusión que contiene los reactivos, ya que del modo en que usted lo ha hecho, en mi opinión, no es apropiado para contestar preguntas detonadoras, debido a que usted ha abierto una nueva sala, que en teoría se entiende deba utilizarse para un nuevo tema de discusión relacionado con el título del Foro, el cuál será respondido a su vez. Y al parecer con su participación, no ha iniciado algún tema de discusión, sino más bien pretende contestar algún reactivo de otra sala de discusión. Por lo tanto, lo invito para el próximo tema, contestar dentro de la sala, y puede generar nuevos temas afuera, si desea iniciar una nueva discusión en otra temática como una sala de discusión nueva.


ATTE:

M.C. Edgar Rangel Lugo.