Punteros opacos

Esta semana comenzamos modificando Eliza para adaptarlo al proyecto. Primeramente explicaremos una técnica que se denomina punteros opacos que permite independizar la definición de un TAD de la implementación. Esto lo vamos a ver claramente con el siguiente ejemplo en el que se presentan cuatro versiones distintas de implementación del TAD pila que responden a la misma interfaz. Usaremos esta técnica en todos los módulos del proyecto, por lo que es importante entenderla correctamente.

Estilo de código y documentación

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:

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:

Saludo

Ejemplo de sencillo de compilación en C bajo GNU/Linux

Este sencillo ejemplo muestra como construir un programa que consta de un módulo principal (main) que utiliza funciones de otro módulo (frases). Si nos fijamos en el módulo main.c este incluye llamadas a las funciones saludo  y despedida cuya implementación se encuentra en el fuente frases.c.

Programa principal

#include <stdio.h>
#include "frases.h"

int main()
{
    printf("%s\n", saludo());
    printf("%s\n", despedida());
    return 0;
}

Este módulo se compone, además, de un segundo archivo frases.h donde se definen los prototipos de las funciones anteriores. El programa principal indica que emplea las funciones del módulo frase mediante la directiva #include "frases.h".

Para construir el programa principal, primeramente hay que compilar por separado cada módulo (opción -c del compilador). El resultado será un archivo objeto (.o) que incluye código máquina no ejecutable. A continuación se enlazan los distintos código objetos para obtener el ejecutable. En el siguiente ejemplo se muestra la compilación, enlazado y ejecucción del ejemplo que hemos visto.

$ gcc -c -Wall frases.c
$ gcc -c -Wall main.c
$ gcc -Wall main.o frases.o -o holamundo
$ ./holamundo
Hola
Adios

Comenzando Proyecto de Programación

¡Hola!

comenzamos proyecto de programación. Para la primera clase vamos a utilizar las siguientes transparencias:

Documentación accesible para la leer la primera semana:

y el resto de documentación en moodle.

Saludos

Recomendaciones para escribir en un foro

tres reglas de oro para participar en un foro:

  • Ser preciso: la pregunta tiene que ser lo más concreta posible. Si se incluye código tiene  estar los más acotado posible al problema. Cómo regla general incluir el mínimo código que pueda reproducir el error. Así mismo es muy útil adjuntar la salida del programa, y si se trata de una violación de segmento, la salida producida por valgrind.
  • Ser claro: tanto en la redacción de la pregunta (evitar errores ortográficos y gramaticales) como en el código. Si el foro al mostrar el código impide leerlo fácilmente (ej. la instalación de Moodle de la UAM) es altamente recomendable emplear una herramienta en línea que permita visualizarlo correctamente (ej. gist, pastebin.com).
  • Ser educado: y respetuoso con el resto de miembros de la comunidad. Ten en cuenta que nadie está obligado a responderte. La mayoría de las comunidades tienen una reglas de publicación que tienen que ser respetadas. Léetelas. Como regla general no preguntes algo que ya haya sido respondido anteriormente.