Comentarios en Java: Tipos y Ejemplos de uso

Basico

Aprende como hacer comentarios en Java. Existen 3 tipos y muchas etiquetas que puedes utilizar para una documentación detallada.

En un programa, los comentarios forman parte en hacer que el programa se vuelva más legible mediante el uso de los detalles del código haciendo que el mantenimiento sea más fácil y pueda encontrarse errores fácilmente. Los comentarios son ignorados por el compilador al compilar un código.

En Java hay tres tipos de comentarios:

  • Comentarios de una sola línea.
  • Comentarios de múltiples líneas.
  • Comentarios de la documentación.

1. Comentarios de una sola línea

Un programador de nivel principiante utiliza comúnmente comentarios de una sola línea para describir la funcionalidad del código. Son los comentarios más fáciles de escribir.

Sintaxis:

//Comentarios aqui ( El texto en esta línea solo se considera comentario )

Ejemplo:

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

2. Comentarios de varias líneas

Para describir un método completo en un código o un fragmento complejo, los comentarios de una sola línea pueden ser tediosos de escribir, ya que tenemos que dar ‘//‘ en cada línea. Entonces, para evitar repetir ‘//‘ en cada línea, podemos utilizar la sintaxis de los comentarios de varias líneas.

Sintaxis:

/*El comentario comienza
continúa
continúa
.
.
.
El comentario termina*/

Ejemplo:

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

También podemos realizar comentarios de una sola línea usando la sintaxis anterior como se muestra a continuación:

/*Línea de comentario 1*/

3. Comentarios de la documentación

Este tipo de comentarios se utilizan generalmente al escribir código para un paquete de proyecto/software, ya que ayuda a generar una página de documentación para referencia, que puede usarse para obtener información sobre los métodos presentes, sus parámetros, etc.

Por ejemplo, http://docs.oracle.com/javase/8/docs/api/java/util/Scanner.html es una página de documentación generada automáticamente mediante el uso de comentarios de documentación y una herramienta javadoc para procesar los comentarios.

Sintaxis:

/**Comienza el comentario
*
*las etiquetas se utilizan para especificar un parámetro
*o método o título
*Las etiquetas HTML también se pueden usar
*como <h1>
*
*el comentario termina*/

Etiquetas disponibles para usar:

Etiquetas disponibles para Comentarios de Documentación
ETIQUETADESCRIPCIÓNSINTAXIS
@authorAgrega el autor de una clase.@author nombre
{@code}Muestra texto en la fuente del código sin interpretar el texto como marcado HTML o etiquetas javadoc anidadas.{@code texto}
{@docRoot}Representa la ruta relativa al directorio raíz del documento generado desde cualquier página generada.{@docRoot}
@deprecatedAgrega un comentario que indica que esta API ya no se debe usar.@deprecated texto-obsoleto
@exceptionAgrega un subtítulo “Throws” a la documentación generada, con el nombre de clase y el texto de descripción.@exception descripción del nombre-clase
{@inheritDoc}Hereda un comentario de la clase heredable más cercana o la interfaz implementable.Hereda un comentario de la superclase inmediata.
{@link}Inserta un enlace con la etiqueta de texto visible que apunta a la documentación del paquete, clase o nombre de miembro especificado de una clase referenciada.{@linkplain package.class#etiqueta-miembro}
{@linkplain}Idéntico a {@link}, excepto que la etiqueta del enlace se muestra en texto plano que en la fuente del código.{@linkplain package.class#etiqueta-miembro}
@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 una sección “Returns” con el texto de descripción.@return descripción
@seeAgrega un encabezado “See Also” (“Ver también”) con un enlace o entrada de texto que apunta a la referencia.@see referencia
@serialUsado en el comentario del documento para un campo serializable predeterminado.@serial campo-Descripción | incluir | excluir
@serialDataDocumenta los datos escritos por los métodos writeObject() o writeExternal().@serialData descripción-datos
@serialFieldDocumenta un componente ObjectStreamField.@serialField campo-nombre campo-tipo campo-descripción
@sinceIndica a partir de que versión de la API fue incluida la clase o método.@since release
@throwsLas etiquetas @throws y @exception son sinónimos.@throws descripción del nombre de la clase
{@value}Cuando {@value} se usa en el comentario del doc de un campo estático, muestra el valor de esa constante.{@value package.class#campo}
@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

Ejemplo:

// Programa Java para ilustrar los usos mas frecuentes
// de Etiquetas de comentarios
 
/**
* <h1>Encuentra un promedio de tres numeros!</h1>
* El programa FindAvg implementa una aplicacion que
* simplemente calcula el promedio de tres enteros y los imprime
* a la salida en la pantalla.
*
* @author  Alex Walton
* @version 1.0
* @since   2017-15-12
*/
public class FindAvg 
{
    /**
    * Este metodo se usa para encontrar un promedio de tres enteros.
    * @param numA Este es el primer parametro para encontrar el metodo Avg
    * @param numB Este es el segundo parametro para encontrar el metodo Avg
    * @param numC Este es el tercer parametro para encontrar el metodo Avg
    * @return int Esto devuelve un promedio de numA, numB y numC.
    */
    public int findAvg(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[]) 
    {
        FindAvg obj = new FindAvg();
        int avg = obj.findAvg(10, 20, 30);
 
        System.out.println("El Promedio de 10, 20 y 30 es: " + avg);
    }
}

Salida:

El Promedio de 10, 20 y 30 es: 20

Para el código anterior, la documentación se puede generar utilizando una herramienta ‘javadoc’:
Javadoc se puede usar ejecutando el siguiente comando en la terminal.

javadoc FindAvg.java
Comentarios en Java
  • 10/10
    Tipos: Una línea, varias lineas, y de documentación - 10/10

Sobre el Autor:

Hey hola! Yo soy Alex Walton y tengo el placer de compartir conocimientos hacía ti sobre el tema de Programación en Java, desde cero, Online y Gratis.

Deja una Respuesta

*

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.