Es fundamental documentar correctamente las aplicaciones software, ya que facilitan la comprensión de las tareas llevadas a cabo por las funciones de cara a que todo el equipo comprenda los códigos y elementos utilizados, a su mantenimiento y a su reutilización.
Todos los lenguajes de programación, ya sean compilados o interpretados, de script, de presentación como HTML o de descripción de datos como XML, permiten introducir textos en lenguaje natural que no serán tenidos en cuenta por los compiladores o intérpretes a la hora de generar o ejecutar ese código.
Estos comentarios permiten a todos los que trabajen con un mismo código fuente, o a uno mismo, tener una documentación en el propio código fuente que explique, aclare o clarifique ciertas funcionalidades del código.
En definitiva, los comentarios son anotaciones ignoradas por los compiladores e intérpretes que ayudan a los programadores de cara a futuros usos del código.
Los comentarios en código fuente suelen ser de dos tipos:
De una sola línea
Vienen marcados por un carácter que señala el comienzo del comentario, el cual se extiende hasta el final de la misma.
De varias líneas
Vienen acotados por un carácter al principio del comentario y otro carácter al final de la última línea que forma dicho comentario.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 |
public class Clase_Prueba { // PROPIEDADES DE CLASE /** * Valor texto. */ private String texto; /** * Valor numerico entero. */ private Integer numero; // ZONA DE CONSTRUCTORES /** * Comentario de metodo simple. */ public Clase_Prueba() { } // ZONA DE LOGICA /** * Otro comentario de metodo simple. */ public void metodo_Uno() { // COMENTARIO DE LINEA // SEGUNDA LINEA DE COMENTARIO } /** * Proceso para probar los comentarios. * * @param numero * Valor numerico entero. * @param fecha * Valor fecha. * @return Cadena devuelta. */ public String metodo_Dos(Integer numero, Date fecha) { return null; } /** * Proceso para probar los comentarios. * * @param texto * Valor texto. * @return Valor numerico. * @throws Exception * Excepcion dada. {@link Exception#getLocalizedMessage()} */ public Integer metodo_Tres(String texto) throws Exception { return null; } } |
Ejemplo de código comentado incluyendo anotaciones Javadoc.
Inclusión en el código
No todos los lenguajes utilizan el mismo juego de caracteres. En la siguiente imagen se muestran los caracteres que utilizan algunos lenguajes para formar los comentarios.
Comentarios en diferentes lenguajes
Generadores de documentación
Los lenguajes de programación habitualmente ofrecen herramientas de generación de documentación de forma automática.
Java tiene javadoc, el cual rastrea los ficheros .java buscando unos comentarios especiales que permiten generar páginas HTML con documentación acerca de estos.
Javadoc genera un fichero por cada .java encontrado, uno para los paquetes (packages.html), otro para la jerarquía de clases (tree.html) y otro con el índice de todos los elementos (AllNames.html).
Ejemplo de la documentación generada con Javadoc.
Anotaciones Javadoc
Los comentarios en Javadoc empiezan con /** y acaban con */. En estos se pueden añadir etiquetas HTML (excepto las de título: <h1>), puesto que Javadoc crea una jerarquía de páginas y títulos.
Se pueden agrupar en las categorías siguientes:
Etiquetas de clase o interfaz
Se ponen antes de la declaración de una clase o interfaz.
Estas etiquetas son:
- @author texto: autor de la clase / interfaz.
- @version texto: versión de la clase / interfaz.
- @see nombreDeClase: crea un hiperenlace.
- @since texto: indica desde cuánto existe.
Etiquetas de atributo
Se deben poner antes de la declaración del atributo:
- @see nombreDeClase: crea un hiperenlace.
Etiquetas de constructor/método
Se colocan antes de la declaración de un constructor o un método:
- @param nombreParametro descripcionParametro.
- @exception nombreClase descripcion.
- @return texto.
- @see nombreDeClase.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
/** * Ejemplo de creación de documentación para Javadoc.<br/> * Podemos incluir etiquetas HTML para enriquecer el texto. * * @author Nombre del autor. * @version 1.0 * @since 25-10-2018. * */ public class Clase_Prueba { /** * Proceso para probar los comentarios. * * @param numero * Valor numerico entero. * @param fecha * Valor fecha. * @return Cadena devuelta. */ public String metodo_Dos(Integer numero, Date fecha) { return null; } /** * Proceso para probar los comentarios. * * @param texto * Valor texto. * @return Valor numerico. * @throws Exception * Excepcion dada. {@link Exception#getLocalizedMessage()} */ public Integer metodo_Tres(String texto) throws Exception { return null; } } |