Autor Tema: Documentar los Proyectos : Doxygen  (Leído 10795 veces)

0 Usuarios y 1 Visitante están viendo este tema.

Desconectado RedPic

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 5362
    • Picmania by Redraven
Documentar los Proyectos : Doxygen
« en: 25 de Octubre de 2007, 15:16:18 »
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: C++
  1. /** \file firmware_iRELE485-628.c
  2.  * \brief Este fichero contiene el cuerpo principal del Firmware del\n
  3.  * dispositivo auxiliar satélite de la iACD V1.0.4. denominado iRELE485-628
  4.  *
  5.  * Integra todos los subsistemas y funciones implementados.\n
  6.  * Source para el compilador CCS C v.3.242
  7.  *
  8.  * Microprocesador : <b>16F628A</b> (18 pines PDIP) \n\n
  9.  * Fuses utilizados: \n
  10.  * \li <b>INTRC</b> Internal RC Osc
  11.  * \li <b>MCLR</b> Master Clear pin enabled
  12.  * \li <b>NOWDT</b> No Watch Dog Timer
  13.  * \li <b>NOPROTECT</b> Code not protected from reading
  14.  * \li <b>NOPUT</b> No Power Up Timer
  15.  * \li <b>NOBROWNOUT</b> No brownout reset
  16.  * \li <b>NOLVP</b> No low voltage prgming, B3(PIC16)
  17.  * \li <b>NOCPD</b> No EE protection
  18.  *
  19.  * \author Diego Márquez García-Cuervo \n
  20.  * <http://picmania.garcia-cuervo.net>
  21.  *
  22.  * \version 1.0.0.A
  23.  */
  24.  

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.  :mrgreen:
 
« Última modificación: 18 de Junio de 2010, 14:35:37 por RedPic »
Contra la estupidez los propios dioses luchan en vano. Schiller
Mi Güeb : Picmania

Desconectado Nocturno

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 17452
    • MicroPIC
Re: Documentar los Proyectos : Doxygen
« Respuesta #1 en: 29 de Octubre de 2007, 14:17:52 »
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?
Un saludo desde Sevilla, España.
Visita MicroPIC                                                                                        ɔ!doɹɔ!ɯ ɐʇ!s!ʌ

Desconectado PalitroqueZ

  • Moderadores
  • DsPIC33
  • *****
  • Mensajes: 5425
    • Electrónica Didacta
Re: Documentar los Proyectos : Doxygen
« Respuesta #2 en: 29 de Octubre de 2007, 19:39:16 »
yo uso uno muy práctico y que reconoce multiples lenguajes (reconoce bucles)  8)

Notepad++

no hará muchas cosas, pero me sirve jeje
« Última modificación: 29 de Octubre de 2007, 19:43:30 por PalitroqueZ »
La propiedad privada es la mayor garantía de libertad.
Friedrich August von Hayek

Desconectado SavageChicken

  • Colaborador
  • PIC24F
  • *****
  • Mensajes: 910
Re: Documentar los Proyectos : Doxygen
« Respuesta #3 en: 03 de Noviembre de 2007, 10:57:20 »
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  8)
No hay preguntas tontas...
Solo hay tontos que no preguntan.

Desconectado stk500

  • Moderadores
  • DsPIC33
  • *****
  • Mensajes: 4735
Re: Documentar los Proyectos : Doxygen
« Respuesta #4 en: 06 de Noviembre de 2007, 02:47:07 »
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

Desconectado Nocturno

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 17452
    • MicroPIC
Re: Documentar los Proyectos : Doxygen
« Respuesta #5 en: 07 de Marzo de 2008, 17:40:13 »
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
Un saludo desde Sevilla, España.
Visita MicroPIC                                                                                        ɔ!doɹɔ!ɯ ɐʇ!s!ʌ

Desconectado reiniertl

  • Moderadores
  • PIC24H
  • *****
  • Mensajes: 1187
Re: Documentar los Proyectos : Doxygen
« Respuesta #6 en: 07 de Marzo de 2008, 20:48:58 »
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

Desconectado RedPic

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 5362
    • Picmania by Redraven
Re: Documentar los Proyectos : Doxygen
« Respuesta #7 en: 07 de Marzo de 2008, 22:46:35 »
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.  :mrgreen:
Contra la estupidez los propios dioses luchan en vano. Schiller
Mi Güeb : Picmania

Desconectado Nocturno

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 17452
    • MicroPIC
Re: Documentar los Proyectos : Doxygen
« Respuesta #8 en: 24 de Marzo de 2008, 03:06:24 »
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  :-/
Un saludo desde Sevilla, España.
Visita MicroPIC                                                                                        ɔ!doɹɔ!ɯ ɐʇ!s!ʌ

Desconectado RedPic

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 5362
    • Picmania by Redraven
Re: Documentar los Proyectos : Doxygen
« Respuesta #9 en: 24 de Marzo de 2008, 03:36:20 »
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.  :mrgreen:
Contra la estupidez los propios dioses luchan en vano. Schiller
Mi Güeb : Picmania

Desconectado damago

  • Colaborador
  • PIC18
  • *****
  • Mensajes: 320
Re: Documentar los Proyectos : Doxygen
« Respuesta #10 en: 24 de Marzo de 2008, 07:51:13 »
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.

Desconectado samshiel_pic

  • Colaborador
  • PIC24F
  • *****
  • Mensajes: 773
    • Electrónica·Ingenia
Re: Documentar los Proyectos : Doxygen
« Respuesta #11 en: 24 de Marzo de 2008, 17:37:32 »
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. :mrgreen: :mrgreen:
Haber si me echais una manita  :D :D

Desconectado migsantiago

  • Colaborador
  • DsPIC33
  • *****
  • Mensajes: 8257
    • Sitio de MigSantiago
Re: Documentar los Proyectos : Doxygen
« Respuesta #12 en: 24 de Marzo de 2008, 19:11:55 »
- Descargandooo -

Un tutorial por favoooorrr  DIegoooo amiiggooooo  :D

Desconectado Nocturno

  • Administrador
  • DsPIC33
  • *******
  • Mensajes: 17452
    • MicroPIC
Re: Documentar los Proyectos : Doxygen
« Respuesta #13 en: 25 de Marzo de 2008, 03:12:55 »
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  :D
Un saludo desde Sevilla, España.
Visita MicroPIC                                                                                        ɔ!doɹɔ!ɯ ɐʇ!s!ʌ

Desconectado migsantiago

  • Colaborador
  • DsPIC33
  • *****
  • Mensajes: 8257
    • Sitio de MigSantiago
Re: Documentar los Proyectos : Doxygen
« Respuesta #14 en: 25 de Marzo de 2008, 11:57:47 »
Bueno.






 :D