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:
/** \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.
