Programación Orientada a Objetos – Semana 4 – Reporte 4
La documentación en cualquier producto es importante, nos dan las instrucciones a seguir en caso de que se genere alguna duda o problema, mucha gente no le da crédito a la documentación de un artículo y por lo general al abrir algo nuevo comenzamos por tirar los instructivos y hasta las pólizas de seguro sin ni siquiera darles un vistazo.
Nosotros como desarrolladores tenemos la obligación de proporcionar a nuestros clientes un documento claro y conciso donde explicamos al funcionamiento de nuestro software; esta será una futura referencia para todos aquellos que quieran ayudarnos a mejorar nuestro software y para guiarlos y que entiendan la visión que tuvimos al momento de construirlo; incluso será una referencia para nosotros mismos ya que en códigos extensos es imposible recordar para que funcionaba y que acción realizaba un segmento de nuestro código.
Por lo general, en los lenguajes de programación que así lo permiten, los comentarios son suficientes para colocar referencias en ciertas partes de nuestro código, sin embargo, existen ciertas herramientas que nos ayudan a generar documentos avanzados que permiten tener una perspectiva más amplia y detallada de las partes y funciones de nuestro software.
JAVADOC
El lenguaje de programación Java incluye una poderosa herramienta que nos permite generar la documentación de nuestro código de manera rápida y bastante profesional, su nombre es JAVADOC.
Javadoc es capaz de generar la documentación de nuestro código de manera instantánea y sin necesidad de abandonar la tradicional sintaxis de los comentarios dentro del código.
Metodología
La forma de generar la documentación por medio de Javadoc es simple, tan fácil como introducir comentarios dentro de nuestro código.
Simplemente tenemos que colocar la explicación ya sea de una clase, método o atributo dentro de un espacio parecido a este:
/***Aqui*pon*el*comentario*
Como pueden ver, el inicio del comentario inicia con una diagonal y DOS asteriscos (los dos asteriscos son parte de la sintaxis de Javadoc, sirven como identificadores) y cada línea empieza con un asterisco y el comentario finaliza con un asterisco y una diagonal.
Si se quiere explicar el funcionamiento de una clase o función, el comentario de Javadoc se coloca justamente arriba de la misma, por ejemplo:
/*** Clase de tipo Animal* Genera un objeto animal*/public class Animal {private String reino;private String familia}
En los métodos se puede colocar un identificador de parámetros que indica, valga la redundancia, los parámetros que dicho método recibe como atributos, para ello de escribe @param, y posteriormente el nombre del parámetro y la explicación del mismo. Así mismo el identificador @return indica el tipo y nombre del valor regresado por el método. Por ejemplo:
/*** Divide un número entre otro número* @param x Dividendo* @param y Divisor* @return El cociente de la division.*/Double division (double x, double y) {…Return cociente;}
Para terminar, se deberá generar la documentación del código escribiendo en la terminal la instruccion Javadoc, con una sintaxis mas o menos asi:
javadoc ubicación
donde "ubicación" deberá sustituirse por la ubicación de nuestro paquete de clases, es como si fueramos a compilar pero utilizando el comando javadoc
Javadoc genera varios archivitos HTML y páginas de estilo CSS que en conjunto formaran una documentación muy parecida a la que encontramos en la página oficial de la API de Java. De igual forma podremos navegar por nuestra página donde veremos el resultado final de todos los comentarios que colocamos dentro del código.
Para más referencias sobre el uso, identificadores, sintaxis o tips acerca de Javadoc se puede visitar la página oficial del proyecto siguiendo esta liga:
javadoc ubicación
donde "ubicación" deberá sustituirse por la ubicación de nuestro paquete de clases, es como si fueramos a compilar pero utilizando el comando javadoc
Javadoc genera varios archivitos HTML y páginas de estilo CSS que en conjunto formaran una documentación muy parecida a la que encontramos en la página oficial de la API de Java. De igual forma podremos navegar por nuestra página donde veremos el resultado final de todos los comentarios que colocamos dentro del código.
Para más referencias sobre el uso, identificadores, sintaxis o tips acerca de Javadoc se puede visitar la página oficial del proyecto siguiendo esta liga:
El link lo agregaré a la barra de Recursos, la cual pueden encontrar en el Sidebar de mi blog.
Saludos!!!
☺ ☻ ☺ ☻
Bien, 5.
ResponderEliminar