Hola

en esta semana vamos a trabajar tanto el estilo del código como la documentación. En moodle tenéis enlaces muy interesantes sobre cómo mejorar vuestro estilo de código, y porqué es importante hacerlo. Respecto a la documetación, unos cuantos consejos orientados a la realización de las prácticas.

Antes de generar la documentación es preciso generarse un archivo de configuración que nos permita personalizar la generación a nuestro gusto.

$doxygen -g

Una vez generado el fichero de configuración Doxyfile se cambiarán las siguientes opciones:

# Optimiza la salida de la documentación para el lenguaje C
OPTIMIZE_OUTPUT_FOR_C = YES
# Extrae la documentación incluso de aquellos elementos que no han sido comentados
EXTRACT_ALL = YES
# Evita generar la documentación en LaTeX
GENERATE_LATEX = NO
# Evita tener que incluir la etiqueta @brief tomando por defecto la primera línea como descripción corta
JAVADOC_AUTOBRIEF = YES

Para no tener que cambiarlas en cada proyecto es recomendable guardarse una copia del fichero de configuración, y utilizar esa copia en vez de generar de cero cada vez.

Hay múltiples maneras de organizar los comentarios. Recomendaría utilizar las siguientes plantillas que cubren tanto el programa principal como la documentación de los módulos.

Ejemplos de documentación:

• Programa principal.
• Fichero de cabeceras de un módulo (.h)
• Fichero de código fuente de un módulo (.c)

Podeis comprobar que las funciones en C se pueden documentar tanto en el fichero de cabeceras como en el fichero de implementación. Cómo regla general no se repite la documentación. En el fichero de cabeceras se describirá qué hace la función, y en el fichero de código fuente que cómo lo hace. Dicho de otra manera, la documentación del .h esta pensada para que la lean otros programadores que no quieran o puedan acceder al código fuente. Así tendrá que incluir todos los detalles necesarios para emplear correctamente las funciones. Mientras que la documentación del .c esta pensada para aquellos que tenga que modificarlo algún día.

Finalmente os dejo un par de enlaces para disfrutar:

• Obfuscated Hello World! o de cómo el estilo importa.
• El mejor comentario que te hayas encontrado en el código.

Saludo