/ ** y / * en comentarios de Java

Cuál es la diferencia entre

/** * comment * * */ 

y

 /* * * comment * */ 

en Java? ¿Cuándo debería usarlos?

La primera forma se llama Javadoc . Usted usa esto cuando escribe API formales para su código, que son generadas por la herramienta javadoc . Por ejemplo, la página de la API de Java 7 usa Javadoc y fue generada por esa herramienta.

Algunos elementos comunes que verías en Javadoc incluyen:

  • @param : esto se usa para indicar qué parámetros se pasan a un método y qué valor se espera que tengan

  • @return : esto se usa para indicar el resultado que el método va a devolver

  • @throws : esto se usa para indicar que un método arroja una excepción o error en el caso de ciertas entradas

  • @since : esto se usa para indicar la versión más antigua de Java que esta clase o función estaba disponible en

Como ejemplo, aquí está Javadoc para el método de compare de Integer :

 /** * Compares two {@code int} values numerically. * The value returned is identical to what would be returned by: * 
 * Integer.valueOf(x).compareTo(Integer.valueOf(y)) * 

* * @param x the first {@code int} to compare * @param y the second {@code int} to compare * @return the value {@code 0} if {@code x == y}; * a value less than {@code 0} if {@code x < y}; and * a value greater than {@code 0} if {@code x > y} * @since 1.7 */ public static int compare(int x, int y) { return (x < y) ? -1 : ((x == y) ? 0 : 1); }

La segunda forma es un comentario de bloque (multilínea). Usted usa esto si quiere tener varias líneas en un comentario.

Diré que solo querrás usar el último formulario con moderación ; es decir, no desea sobrecargar su código con comentarios de bloque que no describen qué comportamientos se supone que tiene el método / función compleja.

Como Javadoc es el más descriptivo de los dos, y puede generar documentación real como resultado de su uso, usar Javadoc sería más preferible que simples comentarios de bloque.

Para el lenguaje de progtwigción Java, no hay diferencia entre los dos. Java tiene dos tipos de comentarios: comentarios tradicionales ( /* ... */ ) y comentarios al final de la línea ( // ... ). Consulte la Especificación del lenguaje Java . Entonces, para el lenguaje de progtwigción Java, ambos /* ... */ y /** ... */ son instancias de comentarios tradicionales, y ambos son tratados exactamente igual por el comstackdor de Java, es decir, son ignorados ( o más correctamente: se tratan como espacios en blanco).

Sin embargo, como progtwigdor de Java, no solo utiliza un comstackdor de Java. Utiliza una cadena de herramientas completa, que incluye, por ejemplo, el comstackdor, un IDE, un sistema de comstackción, etc. Y algunas de estas herramientas interpretan las cosas de manera diferente que el comstackdor de Java. En particular, /** ... */ comentarios son interpretados por la herramienta Javadoc, que se incluye en la plataforma Java y genera documentación. La herramienta Javadoc escaneará el archivo fuente Java e interpretará las partes entre /** ... */ como documentación.

Esto es similar a tags como FIXME y TODO : si incluye un comentario como // TODO: fix this o // FIXME: do that , la mayoría de los IDE resaltarán dichos comentarios para que no te olvides de ellos. Pero para Java, son solo comentarios.

El primero son los comentarios de Javadoc. Pueden ser procesados ​​por la herramienta javadoc para generar la documentación API para sus clases. El segundo es un comentario de bloque normal.

Al leer la sección 3.7 de JLS, explique todo lo que necesita saber sobre los comentarios en Java.

Hay dos tipos de comentarios:

  • / * texto * /

Un comentario tradicional: todo el texto de los caracteres ASCII / * a los caracteres ASCII * / se ignora (como en C y C ++).

  • //texto

Un comentario al final de la línea: todo el texto de los caracteres ASCII // hasta el final de la línea se ignora (como en C ++).


Acerca de su pregunta,

El primero

 /** * */ 

se usa para declarar la tecnología Javadoc .

Javadoc es una herramienta que analiza las declaraciones y los comentarios de documentación en un conjunto de archivos fuente y produce un conjunto de páginas HTML que describen las clases, interfaces, constructores, métodos y campos. Puede usar un doclet de Javadoc para personalizar la salida de Javadoc. Un doclet es un progtwig escrito con la API de Doclet que especifica el contenido y el formato de la salida que generará la herramienta. Puede escribir un doclet para generar cualquier tipo de salida de archivo de texto, como HTML, SGML, XML, RTF y MIF. Oracle proporciona un doclet estándar para generar documentación API de formato HTML. Los documentos también se pueden usar para realizar tareas especiales que no están relacionadas con la producción de documentación API.

Para obtener más información sobre Doclet consulte la API .

El segundo, como se explica claramente en JLS, ignorará todo el texto entre /* y */ tanto se usa para crear comentarios de líneas múltiples.


Algunas otras cosas que tal vez quiera saber sobre los comentarios en Java

  • Los comentarios no anidan
  • /* and */ no tienen ningún significado especial en los comentarios que comienzan con // .
  • // no tiene un significado especial en los comentarios que comienzan con /* or /** .
  • La gramática léxica implica que los comentarios no ocurren dentro de literales de caracteres ( §3.10.4 ) o literales de cadenas ( §3.10.5 ).

Por lo tanto, el siguiente texto es un único comentario completo:

 /* this comment /* // /** ends here: */ 

No creo que las respuestas existentes aborden adecuadamente esta parte de la pregunta:

¿Cuándo debería usarlos?

Si está escribiendo una API que será publicada o reutilizada dentro de su organización, debe escribir comentarios integrales de Javadoc para cada clase public , método y campo, así como también métodos protected y campos de clases no final . Javadoc debe abarcar todo lo que no puede ser transmitido por la firma del método, como precondiciones, postcondiciones, argumentos válidos, excepciones de tiempo de ejecución, llamadas internas, etc.

Si está escribiendo una API interna (una que es utilizada por diferentes partes del mismo progtwig), es posible que Javadoc sea menos importante. Pero para el beneficio de los progtwigdores de mantenimiento, aún debe escribir Javadoc para cualquier método o campo donde el uso o significado correcto no sea inmediatamente obvio.

La “característica principal” de Javadoc es que está estrechamente integrada con Eclipse y otros IDEs. Un desarrollador solo necesita colocar el puntero del mouse sobre un identificador para aprender todo lo que necesita saber al respecto. Referirse constantemente a la documentación se convierte en una segunda naturaleza para los desarrolladores experimentados de Java, que mejora la calidad de su propio código. Si su API no está documentada con Javadoc, los desarrolladores experimentados no querrán usarla.

El primero es para Javadoc que define en la parte superior de las clases, interfaces, métodos, etc. Puede usar Javadoc como el nombre sugerido para documentar su código en lo que hace la clase o qué método hace etc. y generar un informe sobre él.

El segundo es el comentario del bloque de código. Digamos, por ejemplo, que tiene algún bloque de código que no quiere que el comstackdor interprete, entonces usa el comentario de bloque de código.

otro es // esto lo usa en el nivel de statement para especificar lo que se supone que deben hacer las líneas de códigos que siguen.

También hay otros como // TODO, esto marcará que quieres hacer algo más adelante en ese lugar

// FIXME puedes usarlo cuando tienes alguna solución temporal pero quieres visitarla más tarde y mejorarla.

Espero que esto ayude

Los comentarios en la siguiente lista de código Java son los caracteres en gris:

 /** * The HelloWorldApp class implements an application that * simply displays "Hello World!" to the standard output. */ class HelloWorldApp { public static void main(String[] args) { System.out.println("Hello World!"); //Display the string. } } 

El lenguaje Java admite tres tipos de comentarios:

 /* text */ 

El comstackdor ignora todo desde /* hasta */ .

 /** documentation */ 

Esto indica un comentario de documentación (comentario del doc, para abreviar). El comstackdor ignora este tipo de comentario, al igual que ignora los comentarios que usan /* y */ . La herramienta JDK javadoc usa comentarios de documentos al preparar la documentación generada automáticamente.

 // text 

El comstackdor ignora todo desde // hasta el final de la línea.

Ahora con respecto a cuándo deberías estar usándolos:

Use // text cuando quiera comentar una sola línea de código.

Use /* text */ cuando quiera comentar varias líneas de código.

Use /** documentation */ cuando desee agregar alguna información sobre el progtwig que pueda usarse para la generación automática de la documentación del progtwig.

  • Comentario simple, por ejemplo: // comentario
  • Comentario de línea múltiple, por ejemplo: / * comment * /
  • javadoc comment por ejemplo: / ** comment * /

Java admite dos tipos de comentarios:

  • /* multiline comment */ : El comstackdor ignora todo desde /* hasta */ . El comentario puede abarcar varias líneas.

  • // single line : el comstackdor ignora todo desde // hasta el final de la línea.

Algunas herramientas como javadoc usan un comentario especial de varias líneas para su propósito. Por ejemplo /** doc comment */ es un comentario de documentación utilizado por javadoc al preparar la documentación generada automáticamente, pero para Java es un comentario simple de varias líneas.

    Intereting Posts