Saltar al contenido

Cómo escribir comentarios en java

Otra parte común en el código son los comentarios. Dado que los comentarios no se ejecutan, se pueden colocar en cualquier lugar. Los comentarios permiten que el  código sea más fácil de leer para el programador y para otros desarrolladores cuando dan mantenimiento al código. Hay tres tipos de comentarios en Java los cuales son:

  • Comentario de una sola línea.
  • Comentarios de múltiples líneas.
  • Comentarios de documentación (javadoc)

Un comentario de una sola línea comienza con dos barras (//) . Todo lo que escriba después de eso en la misma línea es ignorado por el compilador.

Sintaxis:

//Ejemplo de comentario ( El texto en esta línea solo se considera comentario )

//Programa que muestra comentarios de una sola línea
class Comentarios
{
    public static void main(String args[])
    { 
         // Comentario de una sola linea aquí
         System.out.println("Comentario de una sola linea"); 
    }
}

Comentario de múltiples líneas

Un comentario de múltiples  líneas (también conocido como comentario de varias líneas) incluye cualquier cosa que comience desde el símbolo / * hasta el símbolo * /. Las personas suelen escribir un asterisco (*) al principio de cada línea de un comentario de varias líneas para que sea más fácil de leer, pero no es necesario. 

Sintaxis:

/* Multiple
line comment */

Ejemplo:

//Programa Java para mostrar comentarios de varias líneas
class Persona
{
    public static void main(String args[])
    { 
        System.out.println("Comentarios de multiples líneas a continuación");
        /*Prueba de comentario 1
          Prueba de comentario 2
          Prueba de comentario 3*/
    }
}

Comentario de documentación  (Javadoc)

Este tipo de comentarios se utilizan generalmente al escribir código para un  proyecto/software que contiene mucha funcionalidad, ya que permite generar una página de documentación que sirve como referencia para interpretar la funcionalidad del código sobre las clases,los métodos, sus parámetros, etc.

Sintaxis:

TagDescripciónSintaxis
@authorAgrega el autor de una clase.@author nombre
@deprecatedAgrega un comentario que indica que este código ya no se debe usar.@deprecated código-obsoleto
@paramAgrega un parámetro con el nombre de parámetro especificado seguido de la descripción especificada en la sección “Parámetros”.@param descripción del nombre-parámetro
@returnAgrega un tag «Returns» con una descripción que se especifique.@return descripción
@seeAgrega un encabezado “See Also” (“Ver también”) con un link o entrada de texto que apunta a la referencia.@see referencia
@sinceIndica qué versión de la clase/API fue incluida la clase o método.@since release
@throwsLas etiquetas @throws y @exception son sinónimos. Indican que excepción se lanzara o está definida en el método.@throws descripción del nombre de la clase
@versionAgrega un subtítulo de “Versión” con el texto de versión especificado a los documentos generados cuando se usa la opción -version.@version texto-version

Más información acerca de las eriquetas para documentar en java https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#tag

Ejemplo:

// Programa Java para ejemplificar los usos mas frecuentes
// de  comentarios
 
/**
* <h1>Encuentra un promedio de tres numeros!</h1>
* El programa implementa una aplicacion que
* calcula el promedio de tres enteros y los imprime
* a la salida en la pantalla.
*
* @author  javalio.com
* @version 1.0
* @since   2020-11-27
*/
public class Promedio 
{
    /**
    * Este metodo se usa para encontrar un promedio de tres enteros.
    * @param numA Este es el primer parametro para encontrar el metodo promedio
    * @param numB Este es el segundo parametro para encontrar el metodo promedio
    * @param numC Este es el tercer parametro para encontrar el metodo promedio
    * @return int Devuelve un promedio de numA, numB y numC.
    */
    public int calcularPromedio(int numA, int numB, int numC) 
    {
        return (numA + numB + numC)/3;
    }
 
    /**
    * Este es el metodo principal que hace uso del metodo findAvg.
    * @param args sin usar.
    * @return Nada.
    */
 
    public static void main(String args[]) 
    {
        Promedio obj = new Promedio();
        int avg = obj.calcularPromedio(10, 20, 30);
 
        System.out.println("El Promedio de 10, 20 y 30 es: " + avg);
    }
}