TEMA 8.

Control de
versiones y documentación
Parte 2 - Documentación

Daniel Muñiz Amian 1

 Licencia
Toda la documentación de esta asignatura queda recogida bajo la licencia de
Creative Commons

https://creativecommons.org/licenses/by-nc-nd/4.0/

En el caso de incumplimiento o infracción de una licencia Creative Commons, el autor, como con cualquier otra obra y licencia, habrá de recurrir a los tribunales. Cuando se
trate de una infracción directa (por un usuario de la licencia Creative Commons), el autor le podrá demandar tanto por infracción de la propiedad intelectual como por
incumplimiento contractual (ya que la licencia crea un vínculo directo entre autor y usuario/licenciatario). El derecho moral de integridad recogido por la legislación
española queda protegido aunque no aparezca en las licencias Creative Commons. Estas licencias no sustituyen ni reducen los derechos que la ley confiere al autor; por
tanto, el autor podría demandar a un usuario que, con cualquier licencia Creative Commons, hubiera modificado o mutilado su obra causando un perjuicio a su reputación o
sus intereses. Por descontado, la decisión de cuándo ha habido mutilación y de cuándo la mutilación perjudica la reputación o los intereses del autor quedaría en manos de
cCutacia Juez o Tribunal.

Daniel Muñiz Amian 2

Índice
1. Documentación.

Daniel Muñiz Amian 3

Documentación
Caso práctico

● Evaristo y Hermenegilda saben de la importancia de

tener documentado el código y todo el proceso de
desarrollo de software. Al mismo tiempo que codifican y
refactorizan, dejan constancia documental de lo que van
haciendo. Como están desarrollando con Netbeans, y
con el objetivo de facilitar su trabajo de documentación,
van a utilizar JavaDoc. Eustaquia y Melquiades consiguen
entender el funcionamiento de la aplicación, y la función
de cada método, gracias a los comentarios que insertan
en el código los dos programadores principales.

Daniel Muñiz Amian 4

Documentación
Introducción

● Documentar el código nos sirve para explicar su funcionamiento, punto por punto, de
forma que cualquier persona que lea el comentario, puede entender la finalidad del
código.
● La labor de documentación es fundamental para la detección de errores y para su
mantenimiento posterior, hay que tener en cuenta que todos los programas tienen errores
y todos los programas sufren modificaciones a los largo de su vida.
● Su objetivo no es repetir lo que hace el código, sino explicar por qué se hace.

Daniel Muñiz Amian 5

Documentación
Para ampliar

El siguiente enlace nos muestra el estilo de programación a seguir en Java, así como la forma de
documentar y realizar comentarios de un código. (En inglés)
https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

Daniel Muñiz Amian 6

Documentación
Caso práctico

● Godofredo está aprendiendo muchas cosas con

Hermenegilda.
● Sin embargo hay algunos métodos y clases que ha
implementado Hermenegilda, y que no logra
entender.
● Hermenegilda le comenta que va a incluir
comentarios en su código, y le va a enseñar la
forma correcta de hacerlo.

Daniel Muñiz Amian 7

Documentación
Comentarios

Un comentario es una anotación que se realiza en el código, pero que el compilador va a

ignorar. En principio, los comentarios tienen dos propósitos diferentes:
● Explicar el objetivo de las sentencias. De forma que el programador, sepa en todo
momento la función de esa sentencia.
● Explicar qué realiza un método, o clase, no cómo lo realiza. En este caso, se trata de
explicar los valores que va a devolver un método, pero no se trata de explicar cómo se ha
diseñado.

Daniel Muñiz Amian 8

Documentación
Comentarios. Tipos

Cuando se trata de explicar la función de una sentencia:

● // seguidos del comentario
● con los caracteres /* y */, situando el comentario entre ellos: /* comentario */

Daniel Muñiz Amian 9

Documentación
Comentarios. Tipos

Cuando se trata de explicar la función de una sentencia:

● // seguidos del comentario
● con los caracteres /* y */, situando el comentario entre ellos: /* comentario */

Daniel Muñiz Amian 10

Documentación
Comentarios. Tipos

Cuando se trata de explicar la función de una sentencia:

● // seguidos del comentario
● con los caracteres /* y */, situando el comentario entre ellos: /* comentario */

Daniel Muñiz Amian 11

Documentación
Caso práctico

● Evaristo le explica a Hermenegilda, que para documentar el software, existen diferentes

formas de hacerlo y distintas herramientas en el mercado que automatizan la tarea de
documentación.

Daniel Muñiz Amian 12

Documentación
Automatización de documentación.

● Existen diferentes herramientas que permiten automatizar, completar y enriquecer nuestra

documentación. Podemos citar 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.

Daniel Muñiz Amian 13

Documentación
JavaDoc.

● Para automatizar la generación de documentación utilizando JavaDoc, los comentarios se

deben incorporar al principio de cada clase, al principio de cada método y al principio de
cada variable de clase.
● No es obligatorio, pero en muchas situaciones es conveniente poner los comentarios al
principio de un fragmento de código que no resulta lo suficientemente claro, a lo largo de
bucles, o si hay alguna línea de código que no resulta evidente y pueda llevarnos a
confusión.

Daniel Muñiz Amian 14

Documentación
JavaDoc.

Estos comentarios JavaDoc se escriben empezando por /** y terminando con */, pudiendo
ocupar varias líneas. Este tipo de comentarios tienen que seguir una estructura prefijada.

Hay que tener en cuenta, que si el código es modificado, también se deberán modificar los
comentarios.

Daniel Muñiz Amian 15

Documentación
AUTOEVALUACIÓN

Un comentario en formato JavaDoc.

A. Utiliza los caracteres //

B. Comienzan con /* y termina por */

C. Comienza por /** y terminan por */

Daniel Muñiz Amian 16

Documentación
AUTOEVALUACIÓN

Un comentario en formato JavaDoc.

A. Utiliza los caracteres //

B. Comienzan con /* y termina por */

C. Comienza por /** y terminan por */

Daniel Muñiz Amian 17

Documentación
Caso práctico

● Evaristo va a utilizar JavaDoc para documentar las clases

que ha desarrollado.
● Eustaquia se da cuenta de la ayuda tan importante que
ofrece, tanto para el futuro mantenimiento de la aplicación
como para entender su funcionamiento, tener
documentadas las clases.

Daniel Muñiz Amian 18

Documentación
JavaDoc. Utilización. Clase.

Para documentar una clase, el comentario debe contener al menos las siguientes etiquetas:
● @author: Identifica el nombre del autor de la clase.
● @version: Identifica la versión.
● @since: Identifica la fecha de realización.
● @see: Puede ser recomendable esta etiqueta para referenciar a otras clases o métodos
relacionados.

Daniel Muñiz Amian 19

Documentación
JavaDoc. Utilización. Constructores y métodos.

Dentro de la clase, también se documentan los constructores y los métodos. Al menos se

indican las etiquetas:
● @param: seguido del nombre, se usa para indicar cada uno de los parámetros que tienen
el constructor o método.
● @return: si el método no es void, indica lo que devuelve.
● @exception o @throws: se indica el nombre de la excepción, especificando cuáles pueden
lanzarse.
Los campos de una clase, también pueden incluir comentarios, aunque no existen etiquetas
obligatorias en JavaDoc.

Daniel Muñiz Amian 20

Documentación
JavaDoc. Utilización. Constructores 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, se usa para indicar 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 o @throws: se indica el nombre de la excepción, especificando cuáles pueden
lanzarse.
Los campos de una clase, también pueden incluir comentarios, aunque no existen etiquetas
obligatorias en JavaDoc.

Daniel Muñiz Amian 21

Documentación
Caso práctico

● Para documentar el código, el equipo de desarrollo de NP

Programación, ha decidido utilizar JavaDoc, por lo que
todos los componentes del equipo de desarrollo, deben
familiarizarse con la herramienta.

Daniel Muñiz Amian 22

Documentación
Resumen

● 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.

https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

Daniel Muñiz Amian 23

Documentación
Guía paso a paso

Todo lo visto hasta ahora está muy bonito, pero….

¿Qué genera JavaDoc?

¿Qué te parece si hacemos un ejemplo guiado?

Daniel Muñiz Amian 24

Documentación
Guía paso a paso

Antes de comenzar con la guía, como antecedentes, parto de un proyecto con la siguiente
estructura:

Daniel Muñiz Amian 25

Documentación
Guía paso a paso

En este caso vamos a insertar los comentarios JavaDoc necesarios en la clase Cliente y veremos
como generar la documentación.
Esta parte la podéis realizar con el profesor, teniendo en cuenta que el código fuente de la clase
lo puedes encontrar en la diapositiva siguiente y que ya sabes crear un proyecto nuevo.

Daniel Muñiz Amian 26

Documentación
Guía paso a paso. Código fuente de la clase - CLASE CLIENTE

public class Cliente {

private String nombre;
private String apellido1;
private String apellido2;
private int edad;

public String getNombre() {

return nombre;
}

public String getApellido1() {

return apellido1;
}

public String getApellido2() {

return apellido2;
}

public int getEdad() {

return edad;
}

public void setNombre(String nombre) {

this.nombre = nombre;
}

public void setApellido1(String apellido1) {

this.apellido1 = apellido1;
}

public void setApellido2(String apellido2) {

this.apellido2 = apellido2;
}

public void setEdad(int edad) {

this.edad = edad;
}

public Cliente(String nombreCliente, String apellido1Cliente, String apellido2Cliente, int edadCliente) {

nombre=nombreCliente;
apellido1=apellido1Cliente;
apellido2=apellido2Cliente;
edad=edadCliente;
}

Daniel Muñiz Amian 27

Documentación
Guía paso a paso. Código fuente de la clase

Lo primero que tendremos que comentar es la clase, recuerda que (DIAPOSITIVA 19), debemos
incluir al menos el autor, la fecha y la versión, así como un comentario explicativo.

Daniel Muñiz Amian 28

Documentación
Guía paso a paso. Código fuente de la clase

Lo primero que tendremos que comentar es la clase, recuerda que (DIAPOSITIVA 19), debemos
incluir al menos el autor, la fecha y la versión, así como un comentario explicativo.

Daniel Muñiz Amian 29

Documentación
Guía paso a paso. Código fuente de la clase

A continuación, aunque JavaDoc no obliga a ello, podemos añadir una explicación para cada
uno de los atributos de la clase.

Daniel Muñiz Amian 30

Documentación
Guía paso a paso. Código fuente de la clase

A continuación, aunque JavaDoc no obliga a ello, podemos añadir una explicación para cada
uno de los atributos de la clase.

Daniel Muñiz Amian 31

Documentación
Guía paso a paso. Código fuente de la clase

Tras los atributos vienen los métodos de la clase.

Daniel Muñiz Amian 32

Documentación
Guía paso a paso. Código fuente de la clase

Tras los atributos vienen los métodos de la clase:

- Consultores

Daniel Muñiz Amian 33

Documentación
Guía paso a paso. Código fuente de la clase

Tras los atributos vienen los métodos de la clase:

- Modificadores

Daniel Muñiz Amian 34

Documentación
Guía paso a paso. Código fuente de la clase

Tras los atributos vienen los métodos de la clase:

- Otros

Daniel Muñiz Amian 35

Documentación
Guía paso a paso. Código fuente de la clase

Una vez hemos comentado todo lo que

JavaDoc nos exige y lo que según nuestro
criterio nos parece importante, procedemos a
generar la documentación en HTML.

Daniel Muñiz Amian 36

Documentación
Guía paso a paso. Código fuente de la clase

Una vez hemos comentado todo lo que

JavaDoc nos exige y lo que según nuestro

¿QUÉ HA SUCEDIDO?
criterio nos parece importante, procedemos a
generar la documentación en HTML.

Daniel Muñiz Amian 37

Documentación
Guía paso a paso. Código fuente de la clase

¡Se ha abierto una página HTML con toda la documentación relacionada con el proyecto!

Daniel Muñiz Amian 38

Documentación
Guía paso a paso. Código fuente de la clase

Daniel Muñiz Amian 39

Documentación
Guía paso a paso. Código fuente de la clase

Daniel Muñiz Amian 40

Documentación
Guía paso a paso. Código fuente de la clase

Daniel Muñiz Amian 41