lunes, 26 de septiembre de 2011

Documentación

La documentación consiste en escribir comentarios para explicar el código de manera clara, con el fin de que se entienda lo que hace, ya que con el puro código no es suficiente.

Sin la documentación, nos puede suceder que al momento de retomar el proyecto después de un tiempo, ni nosotros mismos le entendamos. La documentación es importante para que no solo nosotros entendamos, si no que cuando otro programador retome el proyecto logre entenderlo fácilmente.

Una herramienta que podemos utilizar para documentar en Java es Javadoc. Una ventaja es que al momento en que instalamos el JDK, Javadoc se instala. Javadoc nos genera la documentación en un archivo html.

Para poder documentar se utiliza lo siguiente:
/**  Etiqueta  */
Para formar la etiqueta primero se coloca @ y después la palabra reservada.

Las etiquetas más comunes son las siguientes:


Etiqueta
Descripción
@autor
Nombre del autor
@deprecated
Indica que la clase o método son antiguos
@param
Indica parámetro que recibe un método
@return
Indica lo que devuelve el método
@see
Asocia un método o una clase con otro
@throws
Excepción lanzada por método
@version
Versión de la clase o método


Ejemplo

/** 
        * @author José A. Mañas - fprg5000
        * @version 23.9.2005
        */
       public class Circulo {
           private double centroX;
           private double centroY;
          private double radio;
          /**
           * Constructor.
           * @param cx centro: coordenada X.
           * @param cy centro: coordenada Y.
           * @param r radio.
           */
          public Circulo(double cx, double cy, double r) {
              centroX = cx;
              centroY = cy;
              radio = r;
          }
          /**
           * Getter.
           * @return centro: coordenada X.
           */
          public double getCentroX() {
              return centroX;
          }
          /**
           * Calcula la longitud de la circunferencia (perimetro del circulo).
           * @return circunferencia.
           */
          public double getCircunferencia() {
              return 2 * Math.PI * radio;
          }
          /**
           * Desplaza el circulo a otro lugar.
           * @param deltaX movimiento en el eje X.
           * @param deltaY movimiento en el eje Y.
           */
          public void mueve(double deltaX, double deltaY) {
              centroX = centroX + deltaX;
              centroY = centroY + deltaY;
         }
          /**
           * Escala el circulo (cambia su radio).
           * @param s factor de escala.
           */
          public void escala(double s) {
              radio = radio * s;
          }
      }
Para generar la documentación ponemos lo siguiente en la terminal
javadoc Circulo.java


Javadoc nos genera la documentación en html, buscamos el archivo index y al abrirlo nos aparecerá lo siguiente






Referencias

1 comentario:

  1. Ok; sólo recuerda que pedimos que el resumen fuera gráfico.

    Calificación: 4/5

    ResponderEliminar