Comentarios de Java

Los comentarios son la parte de un programa que no se ejecuta. El compilador simplemente ignora los comentarios porque no están destinados a ello. Están escritos en lenguaje "humano" y tienen como objetivo explicar el programa, parte del programa, una sola línea o método para desarrolladores o personas involucradas en el desarrollo. La mayoría de las veces los comentarios están escritos en inglés, es una especie de tradición. En este artículo vamos a hablar sobre los comentarios en Java y cómo utilizarlos correctamente para hacerte la vida más fácil a ti y a tus compañeros de equipo.

Comentarios de Java: por qué son importantes

Dicen que los programadores son extremadamente vagos a la hora de comentar su propio código. Sin embargo, esta es una habilidad muy importante, así que no la subestimes, incluso si recién estás comenzando a aprender Java. El código bien comentado es mucho más valioso que el código sin comentarios porque un programa de este tipo es mucho más fácil de mantener. Dado que los proyectos grandes suelen escribirse en Java, los comentarios competentes también aceleran el desarrollo, ya que al programador le resulta más fácil lidiar con el código de otras personas. Se necesitan comentarios para:

Entiende el código. El tuyo o el de otra persona. Si le parece que no necesita descifrar su propio código porque lo escribió usted mismo, intente abrir un programa relativamente complejo que escribió hace un mes o incluso antes y comprenda rápidamente qué, dónde y por qué tenía en mente. Los comentarios se pueden utilizar para explicar la lógica de un programa o bloque de un programa, así como para dejar recomendaciones para quienes trabajarán con su código más adelante. Este tipo de comentario se puede llamar explicativo.
Contiene información sobre el propósito de los objetos, parámetros de entrada y salida (si los hay), datos sobre el desarrollador y otras cosas importantes relacionadas con el fragmento de código. Dichos comentarios se encuentran en los encabezados de módulos, bibliotecas, procedimientos y funciones. Se les puede llamar comentarios de documentación.
Controle errores y mejore el código. El código cuestionable o el código que necesita mejorar siempre se puede comentar y revisar más adelante. Si se te ocurre que cierto problema se puede solucionar de otra forma, pero ahora no tienes tiempo para ello, escribe esta idea en el comentario. De lo contrario, lo más probable es que, bajo la presión de un nuevo código, lo olvide.

Tipos de comentarios en Java

A pesar de que puedes escribir cualquier cosa en los comentarios, existen ciertos tipos de comentarios en Java y reglas para usarlos. En los comentarios de Java, sea frío:

Comentarios de una sola línea
Comentarios de varias líneas
Comentarios de documentación

Comentarios de una sola línea

Los comentarios de Java más comunes son comentarios de una sola línea. Para indicar dicho comentario, basta con poner una doble barra antes del texto // . Los comentarios de una sola línea se marcan únicamente al principio del comentario. El comentario continúa hasta el final de la línea. Sintaxis:

//here is a single line comment.

Tomemos un ejemplo de este tipo de comentarios Java:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

La salida es:

Este texto es visible para el compilador Java.

Por lo general, un comentario de una sola línea se ubica encima o debajo del lugar comentado en el programa, ocasionalmente en la misma línea. Es importante que quede visualmente claro a qué se refiere el comentario.

Comentarios de varias líneas

A veces no hay suficiente línea para escribir un comentario Java. Por ejemplo, necesita describir cómo funciona un método o una fórmula compleja que está implementando. En este caso, puede escribir varios comentarios de una sola línea, pero sería más racional escribir los llamados comentarios de varias líneas. Están marcados en ambos lados con los símbolos /* */ . Sintaxis de comentarios de varias líneas:

/*This comment
is
Multi line comment
we can describe here
what we need */

Tengamos un ejemplo de comentarios de varias líneas en el código.

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

Comentarios sobre la documentación de Java

Este es un tipo especial de comentarios Java que se utilizan para generar una página de documentación. Por lo general, los desarrolladores escriben comentarios de documentación utilizando Javadoc, un generador de documentación para generar documentación API en formato HTML a partir del código fuente de Java. El formato de documentos utilizado por Javadoc es el estándar de la industria para documentar clases de Java y los IDE más populares, como IntelliJ IDEA y Eclipse, generan automáticamente Javadoc HTML. Los comentarios de la documentación de Java tienen la siguiente sintaxis:

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

Aquí hay un ejemplo: es un fragmento de la clase Java Short . Por cierto, puede ver cualquier código de clase Java desde su IDE (por ejemplo, en IntelliJ IDEA desde Windows, simplemente presione ctrl+LBM o ctrl + b (en Windows) en cualquier nombre de clase o método).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

Aquí está el código Java del conocido y querido método println() por todos los novatos con dicho comentario:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc tiene algunas etiquetas Javadoc especiales marcadas con @ que puedes ver en el código anterior. El ejemplo de una etiqueta Javadoc de este tipo es @author, que agrega un nombre del autor de la clase. Otra etiqueta de Javadoc es @since agrega un comentario que indica que esta clase se usa desde la versión especificada de Java. Escribir buenos documentos Javadoc requiere conocimiento y experiencia (¡y paciencia!). Puede encontrar más información sobre Javadoc en la documentación oficial Cómo escribir comentarios de documentos para la herramienta Javadoc .

PD: algunos ejemplos de comentarios divertidos de la vida real.

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

Para reforzar lo aprendido, te sugerimos ver una lección en video de nuestro Curso de Java