ORGANIZACIÓN Y DOCUMENTACIÓN DE CÓDIGO «C»

La experiencia me ha enseñado que no es fácil (para mí al menos) mantener un recuerdo mental de todo lo que hago. No solo a nivel de detalle sino también a nivel general.

Esto me ha llevado a desarrollar varias veces un mismo código con el esfuerzo extra y desaprovechado que ello supone.

Una de las razones más importantes es la falta de documentación actualizada o simplemente «de documentación», ya sea por las prisas en obtener un buen resultado o por la creencia de que «algo tan simple no puede olvidarse»

Hace unos meses decidí que esta situación no podía seguir así y decidí comenzar a documentar mis trabajos de una forma más efectiva. Documentar en un documento «paralelo» al desarrollo del código es el mejor modo de no tener nunca la documentación actualizada. tener dos editores abiertos es algo incómodo y pasar de uno a otro se acaba evitando, con lo que la documentación sigue siendo igual de mala a pesar de la buena voluntad.

En mi auxilio acudió un viejo conocido: Doxygen. Esta aplicación documenta código directamente (incluso sin escribir nada es capaz de extraer información del código fuente de varios lenguajes, especialmente «C++» y también «C»), pero permite extraer información de los comentarios de un fichero fuente y formatearla para presentarla en un formato cómodo para la lectura (en html o pdf entre otros).

Desde que lo empleo,la documentación ha mejorado notablemente y es más fácil de actualizar y localizar.

A partir de esta experiencia se ha obtenido un resultado adicional interesante: He mejorado la escritura de código. En mi forma de trabajar tendía a hacer el código tan simple como fuese posible para cada proyecto. Esto me llevaba a partir de un código de un proyecto, copiarlo a otro poyecto y modificarlo para implementar lo estrictamente imprescindible. Ahora, al disponer de una documentación más completa, mantengo un módulo en forma de librería, debidamente documentado, y lo empleo directamente ya que es posible acceder a la documentación completa tanto por mi parte como si se entrega al cliente final.

Fiel a mi filosofía,los módulos no son excesivamente genéricos y se trata de módulos relativamente pequeños para no añadir funciones inútiles, código que deba re-compilarse para un proyecto porque tiene definiciones que se resuelvan en tiempo de compilación, o que sea tan complejo que no pueda re-leerse y alterarse cómodamente.

Este curso pretende transmitir este conocimiento puede considerarse una segunda parte del curso de «Sistemas embebidos desde cero«