Comentarios en Java: no todo es tan sencillo

Introducción

Comentarios : parecería que podría ser más sencillo y por qué escribir un artículo completo. Pero no es tan simple. Como dijo mi jefe, cualquiera puede escribir código, pero escribir un buen comentario es difícil. La mayoría de los cursos de idiomas comienzan con el tradicional Hola Mundo. Incluso en los Tutoriales de Oracle, en la sección "Comenzando", comenzamos con el mensaje "¡Hola mundo!" Solicitud . Y desde las primeras líneas de código los vemos: comentarios de Java. Su importancia también se ve enfatizada por el hecho de que en un documento tan importante como la Convención sobre el Código Java, los comentarios se encuentran en una sección separada: Comentarios . Según la documentación, los comentarios en Java se dividen en dos tipos:

• comentario de implementación (o comentario de código);
• comentario documentario.

Los comentarios de código se utilizan para describir líneas/bloques individuales, y los comentarios de documentación se utilizan para describir la especificación del código (su interfaz) independientemente de su implementación. El compilador ignora los comentarios de Java porque tienen sentido para el desarrollador, no para el usuario. Por lo tanto, puede reducir el tamaño de las clases compiladas.

Comentarios de código Java

Por el nombre queda claro que este comentario se relaciona con el código y debe reflejar sus características. Los comentarios del código son:

• Minúsculas (es decir, descritas en una línea)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Bloque (es decir, se describen como un bloque completo, porque no caben en una sola línea)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Una característica interesante de un comentario de bloque es que si lo comenzamos con " /*- " (es decir, agregamos un signo menos después del asterisco), el texto de este comentario de bloque no tendrá formato. Interesante, pero con la ayuda de ciertos comentarios puedes dar algunas sugerencias de IDE. Por ejemplo, utilizando los comentarios en línea " //@formatter:on " y " //@formatter:off " en el IDE de Eclipse, puede deshabilitar el formato de secciones de código. Debe utilizar los comentarios con moderación y sólo cuando sea necesario. Por ejemplo, puedes leer un artículo sobre este tema: "¡No escribas comentarios sobre el código!" . Hay un gran libro llamado Código limpio: creación, análisis y refactorización de Robert Martin. Tiene un capítulo separado “Comentarios”. Como epígrafe de este capítulo, una cita igualmente excelente: “No comentes código incorrecto: reescríbelo” de Brian W. Kernighan y P. J. Plough. Este capítulo se puede encontrar en Google Books . El significado general se puede expresar en una cita suya:

Cada vez que escribes un comentario, haz una mueca de dolor y siéntete como un fracaso".

Está claro que no existe una verdad absoluta y, a veces, son necesarios los comentarios. Pero siempre hay opciones y es necesario luchar contra los comentarios innecesarios. Este capítulo también menciona comentarios inusuales, TODO:

// TODO: Добавить World
System.out.println("Hello, ");

El punto es que se pueden manejar de una manera especial en el IDE. Por ejemplo, en IDEA se recopilan en una pestaña separada, donde puedes verlos: Y un pequeño enigma con un comentario: La línea “http://google.com” es una línea válida dentro del método, porque http aquí es en realidad una etiqueta y luego un comentario. A menudo, muchos comentarios pueden ir desde comentarios de código hasta comentarios de documentación, de los que hablaremos más adelante.

Comentarios para la documentación.

Los comentarios de la documentación describen la API pública. API es la interfaz de programación de aplicaciones, es decir, aquellas clases y métodos que están disponibles para que otros desarrolladores realicen cualquier acción. En resumen, estos comentarios deberían explicar por qué se creó tal o cual clase y paquete y qué hace tal o cual método. También puede describir campos de clase si es necesario. Esto es exactamente lo que vemos en la información sobre herramientas de nuestros IDE, que se presenta como un JavaDoc. Por ejemplo: Si profundizamos en este método, podemos ver de dónde viene este texto: Nuevamente, consulte la Convención de código Java: Convención de código sobre cómo formatear correctamente un JavaDoc . Son algo similares a los comentarios en bloque, pero en lugar de un asterisco (no Asterix) se utilizan dos. Arriba se proporcionó un ejemplo de JavaDoc. No tiene sentido describir todas las posibilidades, ya que esto ya está escrito en la documentación oficial de Oracle. Por lo tanto, miramos todo lo que necesita en la documentación oficial de JavaDoc , sección "Descripciones de etiquetas". Oracle incluso tiene un tutorial separado sobre este tema: Cómo escribir comentarios de documentos para la herramienta Javadoc . La información sobre herramientas en el IDE es buena, pero en realidad son documentos por una razón. En base a estos comentarios de JavaDoc, se genera la documentación. Hay una utilidad javadoc especial para esto . Como podemos ver, ese Tutorial habla de esto. Una descripción de cómo usarlo se encuentra en el sitio web oficial de Oracle para JavaDoc . Para ver usted mismo cómo se ve esto, puede crear un subdirectorio en el directorio con el nombre del paquete, por ejemplo: prueba . Crea una clase simple con comentarios en ella. Por ejemplo:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Después de esto, podemos ejecutar el siguiente comando desde el directorio que contiene nuestro directorio de paquetes: javadoc -d ./test test Luego de esto, veremos el proceso de generación de documentación. Y luego podemos abrir index.html para ver el documento generado. A menudo verás que se publica documentación de API. Por ejemplo, API de Spring Framework .

Conclusión

Como podemos ver, algo tan aparentemente simple como los comentarios resulta mucho más complicado en realidad. Por tanto, si dedicas algo de tiempo a los comentarios y los sigues, tu código será mejor y serás más valioso como programador. #viacheslav