GUIA PARA DOCUMENTAR PROGRAMAS - Portada - Tabla de contenidos e índice - Introducción - Dirección Internet en dónde está la documentación - Descripción del problema a resolver - Planteo (problema ==> solución ==> objetivos ==> plan) - Objetivos - Requerimientos - Abstracción - Especificación de la clase - Operaciones / métodos - Eficiencia - Especificación del programa - Arquitectura del programa - Implementación - Modelo de la clase (dibujo) - Invariante de la clase - Arquitectura interna del programa - Compilador usado - ¿Cómo compilar el programa? - Dificultades encontradas - Soluciones aplicadas - Guía de uso del programa - Datos de prueba del programa - Formato de los datos de prueba - Entradas vs Salidas esperadas - Código fuente - Programa - Clases - Programa de prueba - Reconocimientos - Gracias - Bibliografía Adolfo Di Mare "Convenciones de Programación para Pascal", Revisión 2.0, Reporte Técnico ECCI-01-88, Proyecto 326-86-053, Escuela de Ciencias de la Computación e Informática, Universidad de Costa Rica, 1988. http://www.di-mare.com/adolfo/p/convpas.htm http://www.di-mare.com/adolfo/p/convpas.htm#sec04 Ricardo Villalón: http://profesores.ecci.ucr.ac.cr/Ricardo%20Villalon/ci1201/Guia%20para%20Documentacion%20de%20Tareas.doc Edgar Casasola: http://zafiro.ecci.ucr.ac.cr/ci1201/tarea1/ Java Code Conventionsn (Sun Microsystems, Inc., 1997): - http://java.sun.com/docs/codeconv/CodeConventions.pdf Los alumnos ya saben que si no están conformes con la calificación de la tarea deben hacer su reclamo por escrito al asistente, quien también por escrito les indicará si procede hacer una corrección en la calificación. Los alumnos tienen también derecho a que el profesfor revise su reclamo si no están conformes con la decisión del asistente; para eso es necesario que la respuesta del asistente también quede escrita. Los asistentes ya saben que no es necesario seguir a ciegas la "Guía para Documentar Programas" y saben que en algunos casos no se aplican algunas cosas, mientras que en otros la guía se queda corta. De todas formas, les recuerdo la importancia de acatar las "Políticas de Corrección de Tareas": ================================= Políticas de Corrección de Tareas ================================= * Es muy importante que el programa esté correctamente indentado y que las instrucciones estén debidamante espaciadas. * Es muy importante que en todo el programa haya buena documentación interna. * Uso de Doxygen para la especificación de todos los métodos, funciones y campos de clase. * http://www.di-mare.com/adolfo/p/convpas.htm * http://java.sun.com/docs/codeconv/CodeConventions.pdf +-------------------------------------------------------------------------+ | 1. La falta de cualquier especificación debe ser castigada fuertemente. | | 2. Correcta indentación del código fuente. | | 3. Correcto espaciado del código fuente. | | 4. Código fuente escrito de manera que sea legible y claro. | | 5. Uso de indentificadores significativos. | +-------------------------------------------------------------------------+ ================================================ From: Raquel Fonseca Subject: [CI-1322] Guía de documentación A petición de varios estudiantes, les adjunto una pequeña explicación de lo que se espera que incluyan como mínimo en cada uno de los apartados que menciona la guía de documentación de las tareas programadas: - Portada: debe contener el nombre de la universidad, facultad, escuela, sigla y nombre del curso, nombre del profesor, asignación que se está presentando (Tarea #1 Traducción de avisos económicos a XML), nombre de los estudiantes, junto con el carné, correo electrónico y número de teléfono para poder contactarlos en caso de alguna eventualidad, fecha de entrega. - Tabla de contenidos - Introducción: en el enunciado de la tarea programada se especifica que deben crear una página HTML con la documentación, en esta sección deben incluir la dirección Internet en donde se encuentra. - Descripción del problema a resolver: se incluye el problema a resolver y el análisis del mismo, los requerimiento del programa se se extraen del enunciado del problema, que en este caso contempla todo lo que el sistema debe ser capaz de hacer. Una buena práctica de programación es dividir el problema en subproblemas y con ello, plantear su solución. Todo debe quedar documentado. - Abstracción: aquí se incluye el diseño de la solución propuesta. El diseño incluye la especificación de cada clase, incluyendo la especificación de sus operaciones (métodos) y atributos. Dede indicarse qué tan eficiente es la solución propuesta y brindar una especificación del programa a nivel general de su arquitectura. - Implementación: en esta sección se debe incluir el diagrama de clases, la invariante de la clase, que son todas aquellas clases que no cambian su estado durante la ejecución del programa así como la arquitectura interna del programa que es la implementación de la arquitectura descrita en la abstracción. - Compilador usado. - ¿Cómo compilar el programa? Es importante que explicar el procedimiento paso a paso para compilar el programa, lo cual varía según el lenguaje de programación utilizado. - Dificultades encontradas: Indique cuáles problemas enfrentó y cómo los solucionó. - Soluciones aplicadas: Muchas veces no es obvio el trabajo realizado por lo que es importante dejar constancia de los métodos o ideas que le permitieron llegar a la solución. - Guía de uso del programa: este es el manual de usuario, se incluyen las pantallas que presenta el sistema y cómo se efectúa la interacción con el programa. - Datos de prueba del programa: para verificar que el programa soluciona correctamente el problema planteado, se deben efectuar pruebas. En esta sección se describen cuáles serán las pruebas que se le presentarán al sistema, así como una comparación entre las salidas esperadas y las que el sistema dió como respuesta luego de presentársele cada prueba. - Código fuente: se incluyen todas las clases implementadas tanto para el programa principal como para el programa diseñado para efectuar las pruebas. Los fuentes se entregan en formato digital; no se entregan impresos. - Reconocimientos - Bibliografía: se incluyen todas las fuentes consultadas.