Comentarios sobre Java

En Java, los comentarios son declaraciones no ejecutables que proporcionan explicaciones o anotaciones dentro del código. Se utilizan para mejorar la legibilidad del código y ayudar a los desarrolladores a comprender su finalidad y funcionalidad. El compilador de Java ignora los comentarios durante la ejecución.

Tipos de comentarios

Java admite tres tipos de comentarios:

1. Comentarios de una línea
2. Comentarios multilínea
3. Documentación Comentarios

Comentarios de una línea

Los comentarios de una sola línea empiezan por // y continúan hasta el final de la línea. Se utilizan para breves explicaciones o notas dentro del código.

Syntax

 // This is a single-line comment
int number = 10; // This initializes the variable

Comentarios multilínea

Los comentarios multilínea, también conocidos como comentarios de bloque, comienzan con /* y terminan con */. Son útiles para comentar varias líneas de código o dar explicaciones detalladas.

Syntax

 /*
This is a multi-line comment.
It can span multiple lines.
*/
int number = 20;

Documentación Comentarios

Los comentarios de documentación, o comentarios Javadoc, son comentarios especiales que se utilizan para generar documentación de la API. Empiezan por /** y terminan por */. Estos comentarios suelen colocarse antes de las declaraciones de clases, métodos o campos para describir su finalidad y uso.

Syntax

 /**
 * This is a documentation comment.
 * @param args Command line arguments
 */
public static void main(String[] args) {
    // Code goes here
}

Ejemplos

Ejemplo 1: Utilizar comentarios de una sola línea

 public class SingleLineCommentExample {
    public static void main(String[] args) {
        // Print a message to the console
        System.out.println("Hello, World!"); // Output message
    }
}

Ejemplo 2: Utilizar comentarios multilínea

 public class MultiLineCommentExample {
    public static void main(String[] args) {
        /*
         * This block of code prints a message
         * to the console.
         */
        System.out.println("Hello, Java!");
    }
}

Ejemplo 3: Utilizar los comentarios de la documentación

 /**
 * The Calculator class provides basic arithmetic operations.
 */
public class Calculator {
    /**
     * Adds two integers.
     * @param a First integer
     * @param b Second integer
     * @return Sum of a and b
     */
    public int add(int a, int b) {
        return a + b;
    }
}

Javadoc Tags

Los comentarios Javadoc pueden incluir etiquetas específicas para proporcionar información adicional sobre los elementos de código que describen. Las etiquetas más utilizadas son:

• @param: Describe un parámetro del método.
• @return: Describe el valor de retorno de un método.
• @throws o @exception: Documenta una excepción lanzada por un método.

Consejos y buenas prácticas

• Claridad: Utiliza comentarios para aclarar la lógica compleja del código, pero evita afirmar lo obvio.
• Coherencia: Mantén un estilo coherente para los comentarios en todo el código base.
• Comentarios de actualización: Asegúrate de que los comentarios se actualizan cuando cambia el código para evitar discrepancias.
• Evita comentar en exceso: No abuses de los comentarios; el código debe ser autoexplicativo siempre que sea posible.
• Javadoc: Utiliza comentarios Javadoc en las API públicas para facilitar la generación automática de documentación.