PicManía by RedRaven
 

Búsqueda personalizada

LIGAS

DOCUMENTAR PROYECTOS : DOXYGEN

LINKS
 

Escribir sistemáticamente todo lo relevante a nuestro proyecto, las descripciones de cómo y por qué tomamos esta o aquella decisión, para qué sirve y cómo se utiliza esta función o aquél parámetro.

 


Hay Proyectos y proyectitos. Los Proyectos, con mayúsculas, profesionales o no, pero complejos, largos y/o farragosos son difíciles de mantener vivos conforme pasa el tiempo. ¿Quien no se ha enfrentado a un código fuente propio tras algunos meses, y no digamos años, y no ha entendido absolutamente nada de lo que ese código hacía, ni cómo lo hacía ni por qué hacía lo que hacía?

La memoria de nosotros los programadores es una memoria RAM volátil a corto plazo.

Algoritmos evidentes en si mismos, implementados por cualquiera de nosotros hoy, no es mañana inteligible no a otros programadores, sino ni siquiera por nosotros mismos. Nombres de variables o funciones, que hoy llamamos int2string y mañana int8_to_str, procedimientos, parámetros de entrada o salida, defines, includes ... etc.

La solución para fijar en la memoria todo este galimatías esta en : documentar.

Escribir sistemáticamente todo lo relevante a nuestro proyecto, las descripciones de cómo y por qué tomamos esta o aquella decisión, para qué sirve y cómo se utiliza esta función o aquél parámetro.

Y en nuestra ayuda viene Doxygen, un programa con licencia GNU (o sea: que podemos utilizar alegre y confiadamente sin que nadie venga a sobresaltarnos con demandas, multas, etc.).

Doxygen es una Source code documentation generator tool Herramienta Generadora de Documentación para Código Fuente. Su página Web es Doxygen y en ella está disponible todo lo necesario para su uso y disfrute.

Os lo recomiendo muy encarecidamente, en mi trabajo lo utilizamos por norma y los resultados son espectaculares: Todos los programadores entendemos lo que hacen los otros, nosotros mismos sabemos qué hicimos y como utilizarlo meses después de haberlo olvidado completamente. Y además su documentación generada nos sirve como referencia constante para usarla a diario.

Y por si fuera poco nos obliga también a describir qué estamos haciendo en el momento de hacerlo por lo que nos fuerza a trabajar de forma clara y explicable de cara a los demás.

Un Ejemplo:

Hace unos días hemos publicado un pequeño proyecto titulado: El RS485, un Relé en la lejanía: Hardware y Software. En él se publicaba un código fuente que comenzaba con un curioso párrafo de comentario:
 
/** \file firmware_irele485-628.c
  * \brief Este fichero contiene el cuerpo principal del Firmware del\n
  * dispositivo auxiliar satélite de la iACD V1.0.4. denominado iRELE485-628
  *
  * Integra todos los subsistemas y funciones implementados.\n
  * Source para el compilador CCS C v.3.242
  *
  * Microprocesador : <b>16F628A</b> (18 pines PDIP) \n\n
  * Fuses utilizados: \n
  * \li <b>INTRC</b> Internal RC Osc
  * \li <b>MCLR</b> Master Clear pin enabled
  * \li <b>NOWDT</b> No Watch Dog Timer
  * \li <b>NOPROTECT</b> Code not protected from reading
  * \li <b>NOPUT</b> No Power Up Timer
  * \li <b>NOBROWNOUT</b> No brownout reset
  * \li <b>NOLVP</b> No low voltage prgming, B3(PIC16)
  * \li <b>NOCPD</b> No EE protection
  *
  * \author Diego Márquez García-Cuervo \n
  * <http://picmania.garcia-cuervo.net>
  *
  * \version 1.0.0.A
  */

 
Es cómo se comenta, cara a Doxygen , el contenido de un fichero fuente. Es hacer lo que todos hacemos al inicio de un fichero .c pero teniendo en cuenta lo que Doxygen va a necesitar.

El resto del código fuente continúa del mismo modo comentando variables, defines y funciones.

Es solo un ejemplo, no está documentado al nivel de los que tengo que realizar en mi vida profesional en los que la profundidad de la descripción es mucho mayor pero bien vale como introducción.

Al procesar con Doxygen estos códigos fuentes se generan, en HTML por ejemplo, todas las referencias cruzadas, índices y descripciones detalladas que hagan falta.

El Código Fuente del ejemplo procesado con este script DOX (no os asustéis, tiene un Expert en español para generarlo) generó esta Documentación del iRele485-628 que deseo que visitéis para que veáis los resultados.
 

 

Esta página se modificó el 27/12/2008


Esta página usa la letra Ñ

Nota pública importante sobre las consultas al Webmaster de PicManía.


Sugerencias a Picmanía... (que serán leídas pero seguramente no podrán ser contestadas)

Esta página pertenece al grupo de páginas de Diego RedRaven

 

 



Nota: Esta página Web esta repleta de imágenes, textos, logotipos y demás material extraídos de los mas variados medios de los que no soy ni autor ni depositario de los correspondientes derechos de autor, uso y/o reproducción. Si Ud. es depositario de dichos derechos y desea que el material correspondiente sea eliminado de esta Web no dude en ponerse en contacto conmigo mediante e-mail y será inmediatamente retirado. Gracias.
 
Visitas
Totales : 6847 Hoy: 1 Activas: 1 Vistas: 6847

Esta página fue modificada el 07-08-2010 15:41:25

           
 DmSoft WAMP Escribir Unreal