Herramientas de Documentación de Programas

Lisardo Fernández Cordeiro
1º GII  –  ETSE
Universidad de Valencia


La tecnología, eso que, según algunos entendidos, vino a resolver una serie de problemas que no teníamos, incorpora una cantidad de operativas ajenas a lo mundano que exige un pastoreo  adecuado para la incursión en sus procelosas virtudes. La computación y todos los sistemas de control, basan sus bondades en ingentes líneas de código, cuyo mantenimiento depende de personal debidamente formado pero incapaz de acometerlo sin una adecuada estructura inicial y una suficiente y ordenada documentación. Hagamos, pues, caso a Santo Tomás de Aquino, capaz de llegar a la fe desde la documentación rigurosa de la realidad.

¿qué entendemos por documentación?
Previo a la inmersión en estas cálidas aguas y con ánimo de rebajar las tensiones que se puedan experimentar ante la inevitable circunstancia de no poder esquivar a la literatura, bueno es recordar las reconfortables palabras del siempre referenciado Albert Einstein:
“Si tu intención es describir la verdad, hazlo con sencillez, la elegancia déjasela al sastre.”
La gran falacia de buscar la ciencia huyendo de las letras provoca no pocos dolores de cabeza en los recién llegados que, ante soberana propuesta de documentar lo que con tanta pasión se desarrolla, intentan bordear el arroyo centrando esfuerzos en detalles nimios, por lo sencillo, culminando en documentación poco útil. Así, es muy importante que el aprendiz de sabio se incruste el chip de visión a largo plazo e inicialice el modo “documento lo que hago”. Entrará en el universo de las garantías de mantenimiento de código y la riqueza de las evoluciones sucesivas sin ensuciarse las manos intentando descifrar lo que en su momento fue una inspiración procedente del mismo Valhalla, pero no por ello inmune al paso del tiempo.
Entrando en harina, la documentación escrita que acompaña a todo código que se precie, se suele distinguir según el público objetivo y el tipo de contenido.


documentar la arquitectura y el diseño.
Estos documentos prestan una visión general del proyecto en cuanto al desarrollo y la justificación del modelo elegido. Empiezan a redactarse en las fases iniciales del proyecto y su mantenimiento y actualización supone una ayuda innegable a la correcta evolución del proyecto.
Se pretende con ello, describir el sistema desde un punto de vista de alto nivel del sistema, con objeto de enumerar los componentes del sistema que se han de emplear, justificaciones oportunas de las decisiones tomadas, funcionalidad concreta que se espera y relación entre los componentes citados.


documentar el código fuente
Conforme implementamos los algoritmos, los interfaces, en fin, cuando nos ponemos a teclear líneas de código como si nos fuera la vida en ello, debemos prestar especial atención a la documentación de lo que se va realizando de una manera detallada.
Para cumplir con esta heroica tarea existen dos vertientes diferenciadas, pero igual de válidas.
Por un lado, podemos decantarnos por la escritura del código utilizando formatos analizables por un generador de documentación, como bien puede ser el doxygen –del que hablaremos un poquito más adelante-, naturaldocs o robodoc.  También se puede utilizar un formato ligado a un lenguaje específico como epydoc, javadoc o perldoc. Con estas herramientas se analizará el código generando documentos en uno o varios formatos, a partir de las construcciones del lenguaje y de comentarios especialmente marcados.
Por otro lado, se puede aproximar el lector al modelo literate programming(programación literaria), sistema donde el código fuente se haya incluido en el texto descriptivo. Algo así como describir el programa junto con el código orientado a otros profesionales más que a la ejecución por una computadora. Los fragmentos correspondientes al código se extraen con herramientas específicas.
Es muy recomendable acompañar lo anterior de documentación adicional amparando explicaciones sobre documentación de código, metadocumentación, organización de código, control de versiones, tipos de comentarios, etc.
Pero no perdamos el norte, el objetivo es uno: hacer comprensible el código a programadores ajenos pero que se enfrenten a su mantenimiento, evolución o modificación posterior.


documentar para el usuario final
Debemos pensar, tal y como lo hace el fabricante de nuestra aspiradora preferida, en el usuario no especializado, además de los que puedan tener alguna relación con el código desde un punto de vista de usuario experto o de soporte técnico.
Esta parte de la documentación no tiene mucho que ver con el código, de modo que no es necesario un conocimiento extenso de los entresijos del mismo para poder redactar convenientemente las líneas adecuadas para que sea concisa, breve y fácil de entender.
El sufrido lector debe orientar su pensamiento hacia experiencias en las que, seguro, se ha visto en serios aprietos para salvar dignamente su ego ante circunstancias donde, un buen manual, lo hubiera situado en el olimpo de los freaks.


doxygen
Se trata, tal y como se avanzaba en líneas anteriores, de un documentador automático capaz de extraer la información del propio código fuente. Está basado en la conocida herramienta Javadoc, y se ha puesto de moda gracias a su facilidad de uso, sus múltiples formatos y lenguajes soportados y funcionalidad sin par.
Para generar documentación adecuada al código fuente que pretendemos dejar más bonito que un pincel, debemos editar una plantilla de configuración con los datos más importantes del proyecto.
Veamos algunas etiquetas interesantes:
PROJECT_NAME         Indica el nombre del proyecto sin espacios intermedios
PROJECT_NUMBER    Especifica la versión del programa.
INPUT                            Lista de los nombres de archivos fuente.
FILE_PATTERNS         Extensiones u otro tipo de patrón de nombres, de los archivos a documentar.
EXTRACT_ALL            Documenta un programa que no tiene los estilos de comentario de doxygen.
SOURCE_BROWSER  Se genera una documentación que hace referencia (tiene hiperenlaces) a una copia del código fuente.
OUTPUT_DIRECTORY Especifica el directorio de salida que puede ser absoluto o relativo.
Si bien doxygen es una herramienta la mar de lista, no puede adivinar mucho de lo que el código tiene, a nos que se le indique de un modo adecuado. Así, el formato que normalmente se ha utilizado en C++ para documentar los programas iniciáticos, debe adecuarse levemente para ser correctamente interpretado por esta potente herramienta.
Adicionalmente, dentro de los comentarios del código debidamente formateados, cabe información variada fácilmente codificable con la utilización de una serie de etiquetas especiales que incorpora doxygen.
Las etiquetas más comunes son:
@param                      Información sobre un parámetro de una función.
@return                      Información sobre lo que devuelve una función.
@brief                         Explicación muy breve sobre lo que hace una función, de manera que no sea necesario verse toda la documentación en detalle. Aparece en el índice general.
@note                         Aviso que aparece resaltado en la documentación de una función.
@see                           Permite establecer referencias cruzadas con otras entidades.
Se adjunta un pequeño ejemplo de uso por prescripción facultativa.


conclusión
Siempre, las palabras de los sabios han servido de inspiración y guía en los albores de cualquier actividad, así que nada mejor para concluir que las de Jonathan Nagler, de la Universidad de Nueva York:
«If your program isn’t worth documenting, it probably isn’t worth running».


bibliografía
.. Como documentar un sistema de software. MIT open course Ware.
.. http://mit.ocw.universia.net/6.170/6.170/f01/related-resources/documentation.html
.. Documentación de código. José A. Mañas. 
.. http://www.lab.dit.upm.es/~lprg/material/apuntes/doc/doc.htm
.. Uso de Doxygen. Adolfo di Mare. http://www.di-mare.com/adolfo/p/DoxEsEn.htm
.. Herramientas de documentación ágiles. Sergio Talens-Oliag
.. Documentación de programas. Universidad de Valencia
.. Utilización de la documentación. Javier Abreu Afonso

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *