En programación, además de los comentarios básicos como // o /* */,
también existen los comentarios de documentación, los cuales utilizan el símbolo @.
Estos son usados principalmente en Java y permiten explicar funciones, clases o métodos de una forma estructurada.
Muchas herramientas pueden leer estos comentarios automáticamente y generar documentación técnica.
Ejemplo básico
/**
* Suma dos números enteros.
* @param a Primer número
* @param b Segundo número
* @return La suma de a + b
*/
public int sumar(int a, int b) {
return a + b;
}
Explicación
/** ... */→ Indica que es un comentario de documentación.@param→ Describe cada parámetro que recibe el método o función.@return→ Explica el valor que devuelve el método.
Otros ejemplos de etiquetas @
@author→ Nombre del autor del código.@version→ Número o versión de la clase o programa.@throws→ Explica qué excepciones puede lanzar un método.
Ventajas de los comentarios con @
- Mejoran la comprensión del código por parte de otros desarrolladores.
- Permiten generar documentación automática con herramientas como Javadoc.
- Organizan la información del código de manera clara y profesional.
Lista de las etiquetas @ más usadas en JavaDoc
@author→ Indica el autor del código.@version→ Especifica la versión de la clase o programa.@param→ Describe un parámetro de un método o función.@return→ Explica el valor de retorno de un método.@throwso@exception→ Indica las excepciones que puede lanzar un método.@deprecated→ Señala que un método o clase ya no debe usarse.@see→ Referencia a otra clase, método o documento relacionado.@since→ Indica desde qué versión existe un método o clase.{@code}→ Permite incluir bloques de código dentro del comentario.
