Java tiene tres formas de comentar, no dos. Las dos primeras las conoce todo el mundo; la tercera, Javadoc, es la que convierte un comentario en documentación de verdad.
También te puede interesar
De una sola línea
// Esto es un comentario de una sola línea
System.out.println("esta línea sí se ejecuta");
System.out.println("hola"); // también vale después del códigoEmpieza en las dos barras y termina en el salto de línea. No hay manera de cerrarlo antes.
De varias líneas
/*
Este texto es un comentario de varias líneas:
puede ocupar las que haga falta.
*/
System.out.println("Hola Mundo");/* … */ hay otro */, el comentario se cierra ahí y el resto queda como código suelto, normalmente con un error de compilación raro. Por eso, para comentar un trozo grande que ya tiene comentarios dentro, es más seguro poner // en cada línea: casi todos los editores lo hacen con un atajo.Javadoc, el tercero
Un comentario que empieza por /** —dos asteriscos— no es un comentario normal: es documentación que una herramienta del JDK sabe leer.
/**
* Utilidades de saludo.
*/
public class Saludo {
/**
* Devuelve un saludo para alguien.
*
* @param nombre a quién se saluda
* @return la frase completa
*/
public static String para(String nombre) {
return "Hola, " + nombre;
}
}javadoc -d doc Saludo.java
ls doc/*.htmldoc/Saludo.html doc/allclasses-index.html doc/index-all.html doc/help-doc.html
Sale un sitio web navegable, el mismo formato que la documentación oficial de Java. Las etiquetas que más se usan son @param para cada argumento, @return para lo que devuelve y @throws para cada excepción que puede lanzar. El IDE las lee también: lo que escribas ahí es lo que sale en la ayuda emergente cuando alguien llama a tu método.
javadoc sobre la clase de arriba verás warning: use of default constructor, which does not provide a comment. Es la herramienta recordándote que el constructor implícito tampoco está documentado. Se quita documentando un constructor explícito, o se ignora.Cuándo un comentario sobra
// malo: repite lo que ya dice el código i++; // incrementa i en uno // bueno: dice por qué, que es lo que el código no puede decir i++; // la API numera las páginas desde 1, no desde 0
La regla práctica: si el comentario explica qué hace la línea, normalmente sobra y lo que hay que arreglar es el nombre de la variable. Si explica por qué —una decisión, una limitación de fuera, un caso raro—, ese comentario vale su peso en oro, porque esa información no está en ningún otro sitio.
| Forma | Para qué |
|---|---|
// | una nota corta, o desactivar una línea mientras pruebas |
/* … */ | un bloque; no se puede anidar |
/** … */ | documentación pública de una clase o un método |
Más información en inglés: Code comments in Java.
Todo el código se compiló y se ejecutó con Java 25 LTS en un contenedor limpio antes de publicar esta página; las salidas están copiadas de esa ejecución.