UT4 Documentacion

CICLO: DESARROLLO DE
APLICACIONES WEB
MODALIDAD: DISTANCIA
MÓDULO: ENTORNOS DE
DESARROLLO
UNIDAD DE TRABAJO 4:
OPTIMIZACIÓN Y
DOCUMENTACIÓN
Índice
1.- Refactorización
2.- Control de Versiones
3.- Documentación
3. DOCUMENTACIÓN
Documentación
 Es uno de los aspectos más importantes de la labor de un
programador
 Objetivo: poder entender la finalidad del código.
 Es fundamental para la detección de errores y para su mantenimiento
posterior
 Debe tratar de explicar todo lo que no resulta evidente; explicar por
qué se hace.
 Explicará cuál es la finalidad de una clase, un paquete, qué hace un
método, para qué sirve una variable, qué se espera del uso de una
variable, qué algoritmo se usa, por qué hemos implementado de una
manera y no de otra, qué se podría mejorar en el futuro, etc.
Uso de comentarios.
 Anotación que se realiza en el código (que el compilador ignora) para indicar a los desarrolladores
de código diferentes aspectos del código que pueden ser útiles
 Propósitos
 Explicar el objetivo de las sentencias.
 Explicar qué realiza un método, o clase, no cómo lo realiza.
 Tipos de comentarios
 //comentario de línea
 /*comentario de bloque*/
 /** comentario JavaDoc*/
Al principio de:
Cada clase
Cada método
Cada variable de clase
 No son obligatorios pero sí recomendables.

 Ante una modificación de código, comprobar la posible modificación de comentarios
Documentación de clases
 El desarrollo rápido de aplicaciones muchas veces lleva al descuido de la
documentación.
 Existen herramientas que automatizan, completa y enriquecer nuestra
documentación.
 JavaDoc, SchemeSpy y Doxygen, que producen una documentación
actualizada, precisa y utilizable en línea.
 Insertando comentarios en el código más difícil de entender, y utilizando la
documentación generada por alguna de las herramientas citadas
anteriormente, se genera la suficiente información para ayudar a cualquier
nuevo programador o programadora.
Documentación de clases. JavaDoc
 Tiene que tener el formato /** Comentario*/ . Debe declararse antes de la declaración de
la clase, al principio de cada método y al principio de cada variable de clase.
 Deben incluir al menos las etiquetas
 @author : identifica el nombre del autor o autora de la clase
 @version: la identificación de la versión y fecha.
 @see, para referenciar a otras clases y métodos.
 Dentro de la la clase, también se documentan los constructores y los métodos. Al menos
se indican las etiquetas:
 @param: seguido del nombre, indica cada uno de los parámetros que tienen el
constructor o método.
 @return: si el método no es void, se indica lo que devuelve.
 @exception: se indica el nombre de la excepción, especificando cuales pueden
lanzarse.
 @throws: se indica el nombre de la excepción, especificando las excepciones que
pueden lanzarse
Documentación de clases. JavaDoc
 Generar páginas HTML de documentación a partir de los comentarios incluidos en el
código fuente
 Normas:
 Los comentarios JavaDoc deben empezar por /** y terminar por */.
 Los comentarios pueden ser a nivel de clase, a nivel de variable y a nivel de
método.
 La documentación se genera para métodos public y protected.
 Se puede usar tag para documentar diferentes aspectos determinados del código,
como parámetros.
 Dentro de estos delimitadores se podrán escribir etiquetas HTML, para dar más
formato a la documentación generada
 Más información
Tags más habituales.
¿Cuándo hay que poner un comentario?
 Por obligación (javadoc):
 al principio de cada clase
 al principio de cada método
 ante cada variable de clase
 Por conveniencia (una línea):
 al principio de fragmento de código no evidente
 a lo largo de los bucles
 Y por si acaso (una línea):
 siempre que hagamos algo raro
 siempre que el código no sea evidente
En NetBeans…
 Para analizar Javadoc:

 Menú contextual>>Tools>>Analyze Javadoc
 Para generar Javadoc:

 Menú Run>>Generate Javadoc
JavaDoc en NetBeans…
 Vamos a crear un proyecto nuevo (JavadocPrueba) y. dentro de ese proyecto

crearemos una nueva clase que se va a llamar Prueba
 Al crear NetBeans ya nos deja preparada la misma para introducir el Javadoc
correspondiente.
 Vamos a rellenar este javadoc con el siguiente código:
 Para ver el javadoc que se generaría

podemos pulsar con el botón derecho
sobre el nombre del proyecto y se
elegiría la opción “Generate Javadoc”
 Esto nos genera una estructura en forma de html en nuestra carpeta

dist/javadoc (dentro de la carpeta del proyecto) con varios ficheros y entre ellos
uno de ellos será el fichero index.html.
 Directamente Netbeans nos abre dicho fichero en un navegador con lo que
podemos consultar la estructura creada en forma de html.
 Si pulsamos en nuestra
clase creada (Prueba)
podemos ver los
comentarios que hemos
insertado en la misma.
creada en forma de html.
 Podemos revisar que habíamos añadido unos

tags (etiquetas) @author y @version que sin
embargo no aparecen en nuestro Javadoc
creado.
 Esto es debido a que por defecto no se añaden
al mismo. Pero nosotros podemos configurar en
las propiedades de nuestro proyecto, en la
categoría de Generar (Build) -> Documentando
(Documenting) ciertas propiedades y entre ellas
podemos indicar que sí se incorporen la
próxima vez que se genere.
 Además de marcar las

opciones de @author
y @version, vamos a
indicar también un
título para la ventana
del navegador. Por
ejemplo, podemos
indicar “Javadoc –
JavadocPrueba
 Generamos de
nuevo el Javadoc.
 Podemos
comprobar que ha
cambiado el título
de la ventana y
además ya
aparece esta
información en la
página generada.
 Vamos a crear una nueva clase Empleado en la que vamos a poner en práctica
casi la totalidad de las etiquetas vistas.
 Como documentación de la clase indicaremos la siguiente:
 La clase tendrá una serie de variables que también vamos a documentar
 Podemos ir generando el Javadoc del proyecto, para ver cómo se va quedando

esta nueva clase que hemos añadido (Empleado).
 Podemos comprobar que no se ha generado ninguna de la información indicada

para los atributos.
 Esto es debido a que en las propiedades teníamos desmarcada la opción de
Incluir miembros privados y de paquete(Include Private and Package Private
Members). Marcamos dicha opción y volvemos a generar el Javadoc.
 Ahora ya sí se genera información para los atributos de la clase. Además

tenemos dos opciones: Field Summary y Field Details donde se verá más
información.
 Lo siguiente que vamos a hacer es incorporar los comentarios de documentación

para el constructor de la clase.
 Posteriormente generaremos el Javadoc.

 Al igual que con Field, tenemos dos tablas de información sobre el constructor,
Constructor Summary y Constructor Detail (donde ya aparece la información
metida en las etiquetas).
 Añadimos un método público y generamos el JavaDoc para revisar este método creado.
 Al general el Javadoc, tenemos también un Method Summary y finalmente un Method

Detail (Desde el Method Summary si pulsamos sobre el nombre del Método nos lleva a
su opción de Method Detail respectivamente).
 A continuación añado ahora un método privado. Y generamos el Javadoc

correspondiente.
 Una de las cosas que también tiene de positivo añadir nuestros comentarios en
la creación de métodos, es que estos se podrán consultar desde otra clase que
utilice dicha clase (y dichos métodos).
 Por ejemplo, desde nuestra clase Prueba, creo un nuevo método que se llama
creaEmpleado
 Al poner el “e.” Netbeans nos va a sugerir una serie de métodos y entre ellos
los métodos públicos que tiene dicha clase.
 Si me sitúo encima del método subidasalario nos mostrará toda la información
indicada en nuestro Javadoc
 Si pulsamos sobre la clase (donde pone
javadocprueba.Empleado) nos llevaría también a la
información que hemos insertado sobre la clase en
sí.
 Esta información también sale disponible a la hora

de importar una clase (de esta manera, puedo saber
viendo su descripción, autor o cualquier información)
si es la clase que quiero o no importar.
Y RECUERDA:
 Los comentarios de documentación Javadoc deben colocarse ANTES de las
declaraciones de las clases, de los métodos, o de los atributos.

UT4 Documentacion

Cargado por

Información del documento

Descripción original:

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

UT4 Documentacion

Cargado por

Copyright:

Formatos disponibles

CICLO: DESARROLLO DE

 No son obligatorios pero sí recomendables.

 Para analizar Javadoc:

 Para generar Javadoc:

 Vamos a crear un proyecto nuevo (JavadocPrueba) y. dentro de ese proyecto

 Vamos a rellenar este javadoc con el siguiente código:

 Para ver el javadoc que se generaría

 Esto nos genera una estructura en forma de html en nuestra carpeta

 Podemos revisar que habíamos añadido unos

 Además de marcar las

 La clase tendrá una serie de variables que también vamos a documentar

 Podemos ir generando el Javadoc del proyecto, para ver cómo se va quedando

 Podemos comprobar que no se ha generado ninguna de la información indicada

 Ahora ya sí se genera información para los atributos de la clase. Además

 Lo siguiente que vamos a hacer es incorporar los comentarios de documentación

 Posteriormente generaremos el Javadoc.

 Al general el Javadoc, tenemos también un Method Summary y finalmente un Method

 A continuación añado ahora un método privado. Y generamos el Javadoc

 Esta información también sale disponible a la hora

También podría gustarte