miércoles, 16 de febrero de 2011

POO - Clase 4: Importancia de la documentación técnica


(Imágen cómica de como no debe hacerse la documentación)

La documentación técnica en la programación es sumamente importante por las siguientes razones:


Comprensión de un programa : 

La documentación es necesaria para la comprensión de un programa ya que aunque uno mismo sea el que hizo el programa, sistema o aplicación, muchas veces con el tiempo, por aprender nuevas cosas y querer optimizar o simplemente por no recordar lo que hace cierta parte del programa, nos quedamos sin poder hacer nada en el o tardamos en recuperar la idea de como lo hicimos.

Este tipo de cosas hace muy útil la documentación para uno mismo, pero no es el único aspecto en el que es útil. 

Mantenimiento:

El mantenimiento de un programa es posible gracias a la documentación, ya que no siempre el mantenmiento esta pensado en hacerse por la persona que desarrolló el programa o aplicación, sino muchas veces este es realizado por otras personas que utilizan el programa y lo desean optimizar o modificar para sus propios fines.

Profesionalismo:

Además considero que si uno como programador desea darle una buena presentación a su trabajo(además de una interfaz gráfica vistosa) es necesaria una correcta documentación del programa.
Si claro, comentarios normales en un programa ayudan y con eso es suficiente para un mantenimiento y comprensión, pero el uso de herramientas como JAVADOC y DOXYGEN hace de la documentación técnica algo mas sencillo y vistoso para agregarle al programa.


JAVADOC

Yo personalmente escogí javadoc para realizar la documentación de mi proyecto, ya que lo considero una herramienta potente y completo para ello, y mas que nada doxygen me parece muy sencillo.

Como un "resumen" de el uso de JAVADOC puedo decir que para explicar variables y métodos, esto se hace de la misma manera:
  • Se abren comentarios con "/**" y a continuación se explica la variable o el método.
  • Si se necesita pasar un renglon, éste debe llevar "*" también.
  • Para parámetros y retornos de variables se agrega después del "*" los comandos:
    • @return -variable que se retorna- descripción...
    • @param -variable del parametro- descripción...
  • Al final se cierra con "*/".
Ya documentado el programa lo siguiente es ejecutar en la terminal o cmd, y estando en la carpeta donde se encuentra el archivo .java, el siguiente comando:


En mi caso lo hice de forma diferente para colocar los archivos de la documentación en otra carpeta pero el comando mas básico es: javadoc -nombrearchivo-.java.

Aqui vienen unos ejemplos de su uso: JAVADOC
Y un tutorial muy completo(PERO EN INGLES): Tutorial JAVADOC 

Y aqui un ejemplo de la documentación de una clase de mi proyecto:


Saludos.

2 comentarios:

  1. Necesito que me pases tu documentación. ¿Por qué de repente cambiaste de idioma? ¿Y a qué te refieres con "base primaria" y "base secundaria"?

    Por otra parte, tu captura de pantalla se contradice, ya que tienes comentado que siempre se regresa un valor verdadero y en realidad siempre se regresa un valor falso.

    El resto de la entrada está bien...

    Calificación: 4/5

    ResponderEliminar
  2. -El idioma lo cambié porque como puse en la entrada de taller, me quiero acostumbrar al idioma por ser común en la programación, pero no tendría ningun problema en volver al español.

    -La base de datos primaria sería la principal, donde se tienen los clientes actuales, la secundaria sería como un respaldo donde se guardan los que estuvieron en un pasado en el hotel, solo guardaría nombre, cuarto y en qué fechas estuvo por cuestiones de seguridad.

    -Y una disculpa por la imágen, no es una captura de pantalla, es una imágen cómica que encontré, pero olvide especificarlo(lo agregaré a la publicación).

    Saludos.

    ResponderEliminar