Saltar la navegación

7.2.- Documentación

Para la documentación de nuestras aplicaciones tendremos en cuenta:
Hay que añadir explicaciones a todo lo que no es evidente. Pero, no hay que repetir lo que se hace, sino explicar por qué se hace.

Muestra 11 libros sobre programación sobre la repisa de una estantería.

Documentando nuestro código responderemos a estas preguntas:

  • ¿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? ¿Cuál es el uso esperado de 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?

En la siguiente tabla tenemos un resumen de los distintos tipos de comentarios en Java:

Tipos de comentarios en Java
  Javadoc Una línea Tipo C
Sintáxis

Comienzan con "/**", se pueden prolongar a lo largo de varias líneas (que probablemente comiencen con el carácter "*") y terminan con los caracteres "*/".

Cuenta con etiquetas específicas tipo: @author, @param, @return,...

 Comienzan con "//" y terminan con la línea. Comienzan con "/*", se pueden prolongar a lo largo de varias líneas (que probablemente comiencen con el carácter "*") y terminan con los caracteres "*/".
Propósito Generar documentación externa. Documentar código que no necesitamos que aparezca en la documentación externa. Eliminar código.
Uso Obligado:
  • Al principio de cada clase.
  • Al principio de cada método.
  • Antes de cada variable de clase.
  • Al principio de fragmento de código no evidente.
  • A lo largo de los bucles.
  • Siempre que hagamos algo raro o que el código no sea evidente.
 Ocurre a menudo que código obsoleto no queremos que desaparezca, sino mantenerlo "por si acaso". Para que no se ejecute, se comenta.

Herramienta para la generación automática de la documentación en formato html a partir de los ficheros de código fuente de la aplicación.

Además de lo anterior, al documentar nuestras aplicaciones concurrentes destacaremos:

  • Las condiciones de sincronismo que se hayan implementado en la clase o método (en la documentación javadoc).
  • Destacaremos las regiones críticas que hayamos identificado y el recurso que compartido a proteger.