Documentar los Proyectos : Doxygen

[RedPic]

Después de dar varias vueltas por el foro sin acabar de decidirme dónde colocar este nuevo hilo. Al final me he decidido por el de Proyectos ya que su contenido tiene mucho que ver con ellos, aunque sea en general con todos los proyectos y no con ninguno de ellos en concreto.

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 he posteado un pequeño proyecto en este mismo foro 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:

Código

GeSHi (cpp):
/** \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.

Ea, mañana más.  
 

[Nocturno]

Yo tuve la oportunidad de ver la documentación de tu proyecto del iACD, Diego, y quedé maravillado con la herramienta.
Aún así, siempre me ha dado pereza escribir tanto, limitando mis comentarios a simples líneas encima, enmedio o bajo las funciones que considero que lo necesiten.
Pero es cierto, el paso del tiempo y el ron, y la degradación de las neuronas hacen que luego sea complicadísimo ponerlo en pie.
Le daré una oportunidad a esa herramienta.

JCC40, ¿a qué software te refieres?

[PalitroqueZ]

yo uso uno muy práctico y que reconoce multiples lenguajes (reconoce bucles) 

Notepad++

no hará muchas cosas, pero me sirve jeje

[SavageChicken]

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.

Es totalmente cierto, yo en particular uso assembler y a pesar de no trabajar con erramientas externas para documentar, tengo el hábito de comentar todas las líneas de código, de manera que luego pueda entender que hice y por qué está ahí esa línea, todas la variables, bucles y funciones tienen un comentario lo más claro y consiso posible.
Eso me ha permitido retomar proyectos dejados largo tiempo en espera sin mayores problemas.
Es cierto que no es muy agradable al comienzo, pero incluso al momento de escribir el código ayuda a entender lo que estás haciendo.
Siempre comienzo haciendo una lista, en formato de comentario, con las cosas que debe hacer el programa y luego esa misma lista se transforma en los comentarios de las funciones que se fueron implementando.

Es una práctica muy sana.

Salud 

[stk500]

Doxigen lo encuentros muy interesante, pero el miedo que me da es integrarlo con el WinAVR, aqui espero algunos comentarios y consejo al respecto ya que estoy siguiendo este tema de Redpic

[Nocturno]

Acabo de encontrar este proyecto documentado con Doxygen y se me cae la baba. Qué lástima que yo sea tan indisciplinado para esto.

Po3030k Device Driver for dsPIC33

[reiniertl]

No cabe dudas que me voy a instalar esa cosa, o conseguírmela o lo que haga falta para usarla. Me encantan los programas bien documentados, sobre todo porque no me cuesta mucho escribir cantidad y porque soy de los súper programadores que se acuestan hoy y mañana no saben que rayos han escrito. Como cuando te vas a la cama después de una buena curda y al otro día ni sabes que fue lo que hiciste la noche anterior.

Gracias Diego por tan buen aporte.

Saludos
Reinier

[RedPic]

Venga, todo sea por hacer las cosas mejor. En mi trabajo me lo exigen, es natural ya que mi código fuente puede mañana ser tocado por algún otro programador y tiene que tener disponible la información. Pero ahora estoy cogiéndole el gusto y ya lo coloco las etiquetas Doxygen a todo lo que hago, sea C, Java o Delphi. 

[Nocturno]

Don Diego, gracias por haberme puesto en el camino.

En el proyecto que estoy haciendo me he obligado a usar esta herramienta y no puedo estar más contento con los resultados.

Gracias 

[RedPic]

Don Diego, gracias por haberme puesto en el camino.

En el proyecto que estoy haciendo me he obligado a usar esta herramienta y no puedo estar más contento con los resultados.

Gracias 

A mandar, que pa'eso estamos. 

[damago]

Vaya, como dice Nocturno, yo tambien estoy acostumbrado a comentar sobre el propio codigo lo que considero necesario. Ademas en mi trabajo mi codigo lo toco solo yo (hasta ahora de momento jeje). Es mas, tanto comentar sobre el propio codigo fuente no me acaba de gustar (me gustar ver mas codigo y menos comentarios en los archivos .c).

Por otra parte, los resultados que he visto en tu ejemplo RedPic me han gustado mucho, y es una gozada tener todo tan bien documentado, para ti o para quien venga despues.

El caso es que tambien voy a probarlo, para el programa que llevo entre manos ahora, a ver que tal la experiencia.
Conoces alguna utilidad para crear otro archivo igual que el *.c o *.h  documentado pero sin todo lo comentado par el doxygen? (bueno eso lo podriamos hacer nosotros mismos con un pequeño programita....pero si conoces algo..... debe ser cosa de acostumbrarse, pero no me acaba de gustar revisar un codigo con mas comentarios que codigo (si lo entiendo claro)).

Gracias por el enlace RedPic, creo que es una muy buena herramienta.

Un saludo.

[samshiel_pic]

Hola compañeros que tal va todo??? me ha gustado mucho el Doxygen y me va ha ser muy util pero me veo en un pequeño problema de entendimiento entre él y yo, porque no se como se utiliza.
Haber si me echais una manita 

[migsantiago]

- Descargandooo -

Un tutorial por favoooorrr  DIegoooo amiiggooooo 

[Nocturno]

Instálalo, Migsantiago. Tiene una documentación extraordinaria y muy fácil de entender, como no podía ser de otra manera tratándose de una herramienta para documentar 

[migsantiago]

Bueno.






 

[5GTT]

Yo tambien lo voy a probar, para cosas de casa su utilidad es limitada, pero para proyectos de verdad... creo que no tiene precio.

Habia visto cosas parecidas para proyectos de instalaciones industriales, no sabia que existieran para software.

[RedPic]

- Descargandooo -

Un tutorial por favoooorrr  DIegoooo amiiggooooo 

Miguel Santiago: En cuanto tenga un hueco, ahora estoy de trabajo hasta mas allá de lo razonable, te pongo un hiper-ejemplo: Un programa completo "doxygenado" y la documentación que se genera. De todas formas el ejemplo mini lo tienes en el que puse en el primer post sobre el programa del 485. 

[samshiel_pic]

Hola chicos que tal??
pues llevo ya un rato liado con el doxigen y no consigo los resultados que tienes tu diego no me llega a salir todo el codigo c, no me salen las mismas funciones, vamos que ni idea de que opciones tengo que utilizar para que me saga como a ustedes.
Os dejo los resultados para que veais lo que os digo.

[migsantiago]

Miguel Santiago: En cuanto tenga un hueco, ahora estoy de trabajo hasta mas allá de lo razonable, te pongo un hiper-ejemplo: Un programa completo "doxygenado" y la documentación que se genera. De todas formas el ejemplo mini lo tienes en el que puse en el primer post sobre el programa del 485. 

Gracias Diego, si me gusta la aplicación talvez la use para documentar los programas para mi tesis. 

[samshiel_pic]

Pues haber si a ti te va mejor que a mi migsantiago.

Os adjunto una imagen de lo generado por doxigen y es que no entiendo por que no me salen las lineas de introduccion que estan comprendidas entre el 00001 y el 00043. Pero es que no salen ninguna explicacion del programa en él.

No se haber si me podeis ayudar por que ni no tengo ni papa, jejejeje.