16 feb. 2011

Documentación y herramientas de desarrollo

Programación Orientada a Objetos 
Semana 4 

Avanzando en el proyecto que definimos desde la primer semana, ahora corresponde crear la documentación necesaria, ya que forma parte esencial en el desarrollo de software.

Hasta el momento ya hemos entendido el uso de clases, la herencia y polimorfismo, sabemos que herramientas usaremos y cuales son necesarias, además ya tenemos un código escrito en diferentes archivos, uno para cada clase.

Como ya probablemente nos dimos cuenta, a pesar de no llevar un gran avance en cuanto a código escrito, es posible que ya nos topamos con la dificultad de recordar para que objetivo fue creada cada clase, cada atributo, cada variable. Es aquí donde encontramos una de las razones por las cuales es importante colocar comentarios en cada parte esencial del código, para en dado momento recordar con facilidad con que propósito escribimos cada línea.

Pero que pasará dentro de tres semanas cuando probablemente ya nuestro código este formado por una cantidad considerable de lineas, donde ya hayamos aplicado varios métodos, herencia a clases hijas, etcétera. Nos encontraremos tal vez con no recordar que hacia un cierto método y que parámetros recibe, y buscar donde se encuentra tal método entre tantas clases y entre tantas líneas de código, dificultará el avance a un ritmo apropiado. Aquí es donde aplica una de las razones por la cual es importante la documentación de nuestro software.

La documentación de software consiste en la creación de archivos de texto o en html donde se explique para que sirve cada clase, método, parámetro, etcétera, y donde sea fácil encontrar la relación que existe entre una clase y otra.

La importancia de la documentación de software radica principalmente en ayudar a los programadores cuando se trata de un trabajo en grupo o en equipo, donde cada integrante se hará cargo de una característica especifica del programa o software en el que se trabajará. Sería difícil tener que comunicarse y tener que estar preguntando un integrante a otro, en como esta creando su código, que métodos esta usando y como funcionan cada uno de ellos, tampoco deberá ser necesario tener que ver como funciona la parte del programa que esta creando un compañero para poder continuar con el nuestro. Por eso la documentación ayuda a evitar este tipo de problemas, cada uno muestra que clases tiene, sus métodos y que parámetros reciben, que son cada uno de ellos, y cuál es la función, así los demás en base a esa información pueden trabajar con su parte sin tener que ver el código de otra persona.

Herramientas
Existen varias herramientas para la creación rápida de la documentación como lo son Doxygen, NDoc, javadoc, Castillo de arena, ROBODoc, VAINA y TwinText. Estos crean documentos en base a los comentarios en el código y por lo general organizan en forma de guía de referencia, permitiendo que el programador observe el árbol o desglose de una función.

Dado a que mi programa lo estoy creando en Java, hago uso de la herramienta incluida en el paquete de JDK llamada javadoc, que como ya les mencione, en base a los comentarios que escribamos en nuestro código, genera en este caso documentos en html para visualizar la documentación generada.

Metodología para producir la documentación
El uso de javadoc no tiene mucho de complicado, en pocas palabras, lo que se tiene que hacer es comentar en el mismo código, pero con una cierta estructura para que se logre generar bien.

Para empezar hay que saber que estos comentarios se escriben de la siguiente manera:
/** * Comentarios */
Si vamos a escribir la descripción de una clase, el comentario se coloca arriba de la misma:
/** * Clase principal del programa y nos muestra una ventana en pantalla */ public class Ventana { }
Si hacemos uso de métodos en los que se tenga de entrada algunos parámetros, existe la forma de escribirlo en los comentarios y al momento de generar la documentación los detecte en automático:
/** * Generar una tabla con un numero de columnas y filas * @param c Columnas * @param f Filas */ crearTabla(int c, int f) { }
También existe @return para especificar que es el valor regresado, y no son los únicos, hay unos cuantos más que se tratan en el tutorial que les dejo al final.

Ligas a herramientas
1. How to Write Doc Comments for the Javadoc Tool
2. Javadoc Tool
3. Ejemplo de uso Javadoc

1 comentario: