UT4: OPTIMIZACIÓN Y DOCUMENTACIÓN
Contenido
1 Introducción ................................................................................................................................................ 2
2 ¿Qué hay que documentar?.......................................................................................................................... 3
3 Tipos de comentarios .................................................................................................................................. 3
4 ¿Cuándo hay que poner un comentario? .................................................................................................... 4
5 Javadoc: documentación de Java ................................................................................................................ 5
5.1 Documentación de clases e interfaces ................................................................................................ 6
5.2 Documentación de constructores y métodos ..................................................................................... 7
5.3 Documentación de atributos/variables ............................................................................................... 7
5.4 Ejecución de javadoc ........................................................................................................................... 7
5.5 Una clase comentada .......................................................................................................................... 9
1
1 Introducción
Documentar el código de un programa es añadir suficiente información como para explicar lo
que hace, punto por punto, de forma que no solo los ordenadores sepan qué hacer, sino que
además los humanos entiendan qué están haciendo y por qué.
Documentar un programa es una necesidad, y cuando en realidad se aprecia es cuando hay
errores que reparar o hay que ampliar el programa con nuevas capacidades o adaptarlo a un
nuevo escenario.
Hay dos reglas que no se deben olvidar nunca:
1. Todos los programas tienen errores y descubrirlos solo es cuestión de tiempo y de
que el programa tenga éxito y se utilice frecuentemente.
2. Todos los programas sufren modificaciones a lo largo de su vida, al menos todos
aquellos que tienen éxito.
Por una u otra razón, todo programa que tenga éxito será modificado en el futuro, bien por el
programador original, bien por otro programador que le sustituya. Pensando en esta revisión
de código es por lo que es importante que el programa se entienda: para poder repararlo y
modificarlo.
Otro aspecto que debemos tener en cuenta cuando estamos haciendo un programa, es el estilo
de programación que utilizamos. Existen una serie de recomendaciones que tienen el
consenso de todos los programadores de Java. Entre ellas las más importantes son:
• Los nombres de las clases deben empezar por mayúscula.
• Los atributos y métodos de las clases deben empezar por minúsculas y, si están
formadas por varias palabras, se escriben sin espacios y la primera letra de cada
palabra en mayúscula. En general esta regla sirve para todas las variables.
• Las instancias de las clases siguen la misma recomendación que los métodos y
atributos.
• Las constantes se escriben en mayúsculas.
• Se define una clase por fichero y este fichero se llama igual que la clase.
• Se define dónde guardar los ficheros fuente y dónde los ficheros compilados para
poder usar un control de versiones.
• Se define abrir llaves en una línea nueva – o se usa la notación de Kernighan y Ritchie
(la usada en Java) con la llave { en la misma línea.
• Se define la sangría como 4 espacios.
• El código de un método debe estructurarse en tres partes: cabecera (nombre del
método, parámetros de entrada y tipo devuelto), declaraciones (variables y constantes
usadas) y acciones (cuerpo del algoritmo, es decir, conjunto de instrucciones).
• Se debe utilizar una sola instrucción por línea.
• Se deben usar correctamente los espacios para aumentar la legibilidad.
2
• Se deben utilizar identificadores significativos, que permitan entender qué datos van a
contener o cuál es la utilidad del método o la clase, pero sin hacerlos demasiado largos
y engorrosos.
• Se puede exigir poner comentarios en estilo Javadoc u otra herramienta de
documentación automatizada.
En general, en Java se suele utilizar el estilo "UpperCamelCase" en los identificadores de
clases, interfaces y enumerados. Mayúsculas para las constantes (todas sus letras) y
"lowerCamelCase" para los identificadores de métodos o variables. Los nombres de paquetes
van siempre en minúsculas.
Aún hoy en día se sigue considerando vigente el clásico manual de buenas prácticas y estilo
de programación en Java, creado por Sun Microsystems en 1997 (lo tienes traducido en el
AV):
https://www.oracle.com/technetwork/java/codeconventions-150003.pdf
2 ¿Qué hay que documentar?
Hay que añadir explicaciones a todo lo que no es evidente. No hay que repetir lo que se hace,
sino explicar por qué se hace. Esto se traduce en:
• ¿De qué se encarga una clase? ¿Un paquete?
• ¿Qué hace un método?
• ¿Cuál es el uso esperado de un método?
• ¿Para qué se usa una variable?
• ¿Qué algoritmo estamos usando? ¿De dónde lo hemos sacado?
• ¿Qué limitaciones tiene el algoritmo? ¿... la implementación?
• ¿Qué se debería mejorar... si hubiera tiempo?
3 Tipos de comentarios
En Java disponemos de tres notaciones para introducir comentarios:
javadoc
Comienzan con los caracteres "/**", se pueden prolongar a lo largo de varias líneas
(que probablemente comiencen con el carácter "*") y terminan con los caracteres
"*/".
Una línea
Comienzan con los caracteres "//" y terminan con la línea
Tipo C
3
Comienzan con los caracteres "/*", se pueden prolongar a lo largo de varias líneas
(que probablemente comiencen con el carácter "*") y terminan con los caracteres
"*/".
Cada tipo de comentario se debe adaptar a un propósito:
Javadoc:
• Para generar documentación externa.
Una línea, tipo C:
• Para documentar código que no necesitamos que aparezca en la documentación
externa (la que genera javadoc).
• Para eliminar código. Ocurre a menudo que código obsoleto no queremos que
desaparezca, sino mantenerlo "por si acaso". Para que no se ejecute, se comenta.
4 ¿Cuándo hay que poner un comentario?
Por obligación (javadoc):
1. Al principio de cada clase (interfaz, enum…)
2. Al principio de cada método
3. No es obligatorio comentar cada variable de clase
Por conveniencia (una línea):
4. Al principio de fragmento de código no evidente
5. A lo largo de los bucles
Y... por si acaso (una línea):
6. Siempre que hagamos algo raro
7. Siempre que el código no sea evidente
Y una advertencia importante, cuando un programa se modifica, los comentarios deben
modificarse al tiempo, de lo contrario podría ocurrir que los comentarios acaben refiriéndose
a un algoritmo que ya no utilizamos.
4
5 Javadoc: documentación de Java
Es muy importante insertar comentarios en el código para documentar las tareas que realiza y
los pasos que se sigue para ello. Por otro lado, en muchos casos es necesario aportar al
destinatario del software documentación técnica que indique la funcionalidad del software.
Como ya hemos visto antes, hay dos tipos de comentarios:
• Documentación de uso interno. La persona que desarrolla el código inserta
comentarios para detallar aspectos del código generado. Estos comentarios sirven para
que, en un futuro otra persona o ella misma pueda comprender qué tarea desarrolla el
código de una forma rápida.
• Documentación de uso externo. Documentación pensada para que otras personas
comprendan y utilicen el código generado y que se tenga en cuenta para desarrollos
posteriores. Un claro caso es la documentación de las API y los Framework de
programación donde las funciones tienen perfectamente detallada su funcionalidad y
uso.
El paquete de desarrollo Java incluye una herramienta, javadoc, para generar un conjunto
de páginas web a partir de los ficheros de código. Esta herramienta toma en consideración
algunos comentarios para generar una documentación bien presentada de clases y
componentes de clases (variables y métodos).
Aunque javadoc no ayuda a la comprensión de los detalles de código, sí ayuda a la
comprensión de la arquitectura de la solución, lo que no es poco. Se dice que javadoc se
centra en la interfaz (API - Application Programming Interface) de las clases y paquetes
Java.
Javadoc realza algunos comentarios, de los que exige una sintaxis especial. Deben
comenzar por "/**" y terminar por "*/", incluyendo una descripción y algunas etiquetas
especiales:
/**
* Parte descriptiva.
* Puede consistir en varias frases o párrafos.
*
* @etiqueta texto específico de la etiqueta
*/
Estos comentarios especiales deben aparecer justo antes de la declaración de una clase, un
campo o un método, en el mismo código fuente. En las siguientes secciones se detallan las
etiquetas (tags) que javadoc sabe interpretar en cada uno de los casos.
Como regla general, hay que destacar que la primera frase (el texto hasta el primer punto)
recibirá un tratamiento destacado, por lo que debe aportar una explicación concisa y
contundente del elemento documentado. Las demás frases entrarán en detalles.
5
En Eclipse, para generar documentación, usamos la opción que nos aparece en la pestaña
Project:
A continuación, se nos pedirán más datos para generar la documentación: ruta de
javadoc.exe, ruta donde se dejará la documentación…
5.1 Documentación de clases e interfaces
Al documentar una clase se debe incluir al menos:
1. Nombre de la clase, descripción general, número de versión, nombre de autores.
2. Documentación de cada constructor o método (especialmente los públicos)
incluyendo: tipo de retorno, nombres y tipos de parámetros si los hay, descripción
general, descripción de parámetros (si los hay), descripción del valor que devuelve y
excepciones si las lanza.
Deben usarse al menos las etiquetas:
• @author
• @version
@author nombre del autor
@version identificación de la versión y fecha
@see referencia a otras clases y métodos
6
5.2 Documentación de constructores y métodos
Deben usarse al menos las etiquetas:
• @param
una por argumento de entrada
• @return
si el método no es void
• @exception o @throws
una por tipo de Exception que se puede lanzar (si las hay)
@param nombre del parámetro descripción de su significado y uso
@return valor devuelto descripción de lo que se devuelve
@exception nombre de la excepción excepciones que pueden lanzarse
@throws nombre de la excepción excepciones que pueden lanzarse
@exception y @throws se pueden usar indistintamente.
5.3 Documentación de atributos/variables
Ninguna documentación es obligatoria
5.4 Ejecución de javadoc
La mayor parte de los entornos de desarrollo incluyen un botón para llamar a javadoc
así como opciones de configuración.
No obstante, siempre se puede ir al directorio donde instaló el JDK y ejecutar
javadoc directamente sobre el código fuente Java:
...> {directorio de instalación}/javadoc *.java
La herramienta javadoc admite muchas opciones. Algunas de las más usadas
aparecen a continuación:
usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]
-public Show only public classes and members
-protected Show protected/public classes and members
(default)
-package Show package/protected/public classes and members
-private Show all classes and members
-sourcepath <pathlist> Specify where to find source files
-classpath <pathlist> Specify where to find user class files
-verbose Output messages about what Javadoc is doing
7
-d <directory> Destination directory for output files
-version Include @version paragraphs
-author Include @author paragraphs
-docfilessubdirs Recursively copy doc-file subdirectories
-splitindex Split index into one file per letter
-windowtitle <text> Browser window title for the documenation
-doctitle <html-code> Include title for the overview page
-header <html-code> Include header text for each page
-footer <html-code> Include footer text for each page
-bottom <html-code> Include bottom text for each page
javadoc -help despliega un catálogo completo de opciones.
Resumen:
La herramienta javadoc del JDK proporciona una herramienta para generar páginas
HTML de documentación a partir de los comentarios incluidos en el código fuente.
Para que javadoc pueda generar los textos HTML es necesario que se sigan unas
normas de documentación en el fuente, que son las siguientes:
• Los comentarios de documentación deben empezar con /** y terminar con
*/.
• Se pueden incorporar comentarios de documentación a nivel de clase, a nivel
de variable (dato miembro) y a nivel de método.
• Se genera la documentación para miembros public y protected.
• Se pueden usar tags para documentar ciertos aspectos concretos como listas de
parámetros o valores devueltos. Los tags se indican a continuación.
Tipo de tag Formato Descripción
Permite crear una referencia a la documentación
Todos @see
de otra clase o método.
Comentario con datos indicativos del número de
Clases @version
versión.
Clases @author Nombre del autor.
Clases @since Fecha desde la que está presente la clase.
Métodos @param Parámetros que recibe el método.
Métodos @return Significado del dato devuelto por el método
Métodos @throws Comentario sobre las excepciones que lanza.
Métodos @deprecated Indicación de que el método es obsoleto.
Toda la documentación del API de Java está creada usando esta técnica y la herramienta
javadoc.
8
5.5 Una clase comentada
import java.util.*;
/** Un programa Java simple.
* Envía un saludo y dice qué día es hoy.
* @author XXX empresa YYYYYY
* @version 1 21/11/2022
*/
public class HolaATodos {
/** Único punto de entrada.
* @param args Array de Strings.
* @return No devuelve ningún valor.
* @throws No dispara ninguna excepción.
*/
public static void main(String [ ] args) {
System.out.println("Hola a todos");
System.out.println(new Date());
}
Ejemplo:
package figuras;
/**
* Una clase para representar círculos situados sobre el plano.
* Cada círculo queda determinado por su radio junto con las
* coordenadas de su centro.
* @version 1.1, 10/03/2022
* @author Esther
*/
public class Circulo {
protected double x,y; // coordenadas del centro
protected double r; // radio del círculo
/**
* Crea un círculo a partir de su origen y su radio.
* @param x La coordenada x del centro del círculo.
* @param y La coordenada y del centro del círculo.
* @param r El radio del círculo. Debe ser mayor o igual a 0.
*/
public Circulo(double x, double y, double r) {
this.x=x; this.y = y; this.r = r;
}
9
/**
* Cálculo del área de este círculo.
* @return El área (mayor o igual que 0) del círculo.
*/
public double area() {
return Math.PI*r*r;
}
/**
* Indica si un punto está dentro del círculo.
* @param px componente x del punto
* @param py componente y del punto
* @return true si el punto está dentro del círculo o false en otro caso.
*/
public boolean contiene(double px, double py) {
/* Calculamos la distancia de (px,py) al centro del círculo (x, y),
que se obtiene como raíz cuadrada de (px-x)^2+(py-y)^2 */
double d = Math.sqrt((px-x)*(px-x)+(py-y)*(py-y));
// el círculo contiene el punto si d es menor o igual al radio
return d <= r;
}
}
10
