Programación Orientada a Objetos. Curso 06/07
Guía para la elaboración de memorias de prácticas
Consideraciones iniciales: ¿Para qué sirve una memoria?
En las clases de prácticas, su uso principal es como lectura antes de entrar a evaluar el
código de una entrega. Es
decir, debe responder de forma rápida y directa a las siguientes
preguntas: ¿qué han hecho y cómo? ¿por qué así y no de otra manera?
¿cómo
lo han probado?.
De cara a vuestra vida profesional, esto es un ejercicio de
redacción de documentación técnica. Todo código que se escriba o
mantenga deberá ir acompañado de documentación. Si esta documentación
no es clara y legible, el mantenimiento del código se dificulta de
sobremanera. Además, en un entorno de producción, hay que cuidar la
presentación de la documentación, ateniéndose a reglamentos internos
sobre estilos de portada, estructuración del contenido y tipos de
fuentes admisibles.
Estructura recomendada de una memoria
Una memoria debe consistir de portada, introducción, análisis y pruebas:
Portada (1 página, o bastante menos en el
caso de documentación .html),
En la que aparezca:
- El nombre de la asignatura,
- El nombre y número de la práctica,
- La letra de grupo de la pareja de prácticas, y su número
- El nombre de ambos integrantes de la pareja.
- Se recomienda tambien incluir las direcciones de correo de ambos
integrantes.
Introducción (dos o tres párrafos),
En la que se explica de forma resumida
el objetivo de la práctica. No se trata de copiar el enunciado, sino de
resumirlo en pocas palabras, para dar pie a las explicaciones
posteriores.
Análisis del problema (hasta 6 caras,
según complejidad),
En el que se explican cómo se ha
afrontado el problema y qué es lo que se ha hecho.
Se recomienda:
- Incluir discusiones sobre métodos alternativos de resolución, y
porqué no se han elegido.
- Usar pseudocódigo para explicar fragmentos de código
especialmente importantes.
- Usar esquemas cuando resulten ilustrativos (ascii-art inclusive).
Se debe evitar por todos los medios:
- Incluir código java real, o javadoc, o enumerar todas las clases
generadas junto con sus funciones. Sólo se deben incluir "firmas" de
funciones (la firma de un
método en Java es equivalente al prototipo
de una función en C) cuando esa función merezca una explicación más detallada, pero nunca como regla
general.
- Incluir esquemas que no aporten información nueva y relevante.
Pruebas (en torno a 1 cara)
En la que se detallan aspectos de
control de errores y el tipo de pruebas al que ha sido sometido el
programa. La sección de pruebas debe detallar:
- El tipo de condiciones de error que el programa puede detectar
y cómo se comportará ante ellas.
- Aquellas condiciones de error que no están contempladas.
- Una enumeración de las pruebas a las que ha sido sometido el
programa. No se trata de proporcionar un volcado de pantalla de N
ejecuciones, sino de proporcionar a un futuro mantenedor la descripción
de una serie de pruebas que se sabe que funcionan. Y las que no.
Comentarios
(opcional, longitud variable).
Esta
sección no aparecería en una entrega "profesional", y sirve para dejar
comentarios al profesor del tipo de "queríamos hacer X pero no lo
hicimos por falta de tiempo" o "sabemos cómo hacer Y, aunque no lo
hemos hecho, y queremos explicarlo". O incluso quejarse de partes del
enunciado.
Si se tienen problemas durante la
realización de la práctica, es muy recomendable detallarlos en esta
sección. Si una práctica no funciona, y en ningún lugar de la memoria
se comenta el fallo, da la impresión de que se está intentando colar
gato por liebre.
Presentación y estilo de redacción
Una memoria de prácticas es
un entrenamiento para la documentación técnica y las descripciones de
proyectos que os esperan en vuestra vida profesional. Se debe extremar
el cuidado con la claridad de la redacción y la corrección ortográfica
del texto. En este último punto, se ruega encarecidamente el uso de
correctores ortográficos como parte de la elaboración de la práctica.
En cuanto a la presentación, es importante evitar el uso de fuentes
no estándar o colores chillones en la memoria de la práctica. También
se recomienda mantener una estructura clara a lo largo del texto, con
apartados y subapartados según se juzgue necesario. Si bien estos
aspectos "estéticos" cuentan mucho menos que el contenido en sí en la
nota de una práctica, no está de más invertir el escaso tiempo
necesario para dejar las memorias elegantes, legibles, y bien
estructuradas. Y los profesores lo agradecerán.
(C) 2006-2007, Escuela Politécnica Superior, UAM