DOCUMENTACION Profesor Edgar Casasola http://zafiro.ecci.ucr.ac.cr/ci1201/tarea1/ ANEXO 1. ¿QUE SON LAS TAREAS PROGRAMADAS O PROYECTOS? Tradicionalmente se define como tarea programada a un proyecto de programación asociado a un problema con un nivel intermedio de dificultad. Se entiende por problema intermedio aquel que puede ser resuelto con los conocimientos adquiridos durante cada módulo, pero que no presenta una solución inmediata obvia. Estos proyectos tienen como objetivos fundamentales: 1. Propiciar el trabajo en equipo 2. Mejorar las técnicas de comunicación oral y escrita 3. Aumentar el nivel crítico y la autodisciplina 4. Gestionar el autoaprendizaje 5. Proporcionar una apertura didáctica que sirva de disparador para dinámicas de trabajo en clase En este curso se tiene definida una tarea programada diagnóstica y una tarea programada por módulo. Cada una de ellas tiene el objetivo de utilizar e incorporar los conocimientos adquiridos de forma acumulativa en el curso anterior y en cada uno de los módulos del curso. ANEXO 2. DOCUMENTACIÓN DE LAS TAREAS PROGRAMADAS Un buen profesional en computación debe aprender a crear reportes y documentación que soporte el código fuente y en el cual se especifican los detalles del programa que se está presentando y el estado actual del mismo. La documentación es una descripción de los programas que se desarrollan y de las particularidades del mismo. En este apartado se describen las características mínimas que debe tener la documentación que debe acompañar cada una de las tares programadas. A. ASPECTOS DE FORMATO Y CONTENIDO 1. Portada. La cual debe incluir como mínimo la información para contextualizar el trabajo en cuanto al lugar, tiempo, y autor del trabajo o autores. Por lo tanto debe incluir: El nombre de la Universidad o Centro de Estudio, Facultad (si aplica), Escuela o Carrera que cursa, nombre del curso, identificación del grupo, nombre del profesor, nombre y número de identificación de cada estudiante, dirección de correo electrónico y/o número de teléfono donde se puede contactar al estudiante, y finalmente la fecha en que se entrega el trabajo. 2. Índice con números de página 3. Introducción Debe incluir como mínimo: - Descripción del problema a resolver. - Descripción de la metodología o forma de trabajo utilizada para resolver el problema incluyendo distribución de funciones entre los miembros del grupo, y el rol de cada uno. En caso de duda se llevará a cabo una validación del aporte de trabajo individual. - Descripción del resto del trabajo. 4. Análisis del problema Debe incluir los aspectos importantes que se tomaron en cuenta a la hora de descomponer el problema. Por ejemplo: se deben documentar las dudas que se presentaron durante el desarrollo del trabajo y que tuvieron relevancia en cuanto a la interpretación del problema. Se debe incluir cualquier premisa que no se presentaba de manera explícita en el enunciado del problema y sobre las cuales se trabajó, especialmente la descripción de cualquier cosa que se asumió como parte del problema. Valores de entrada al programa e interfaz o modo de interacción con el mismo. Se deben presentar las decisiones que fueron claves para el desarrollo del trabajo. Deben recordar que un buen programador se debe apegar rigurosamente a la especificación del problema que se le plantea. Por lo tanto, en este análisis solo se debe asumir detalles que en la especificación presentan un cierto grado de ambigüedad o que no quedan muy claros. 5. Diseño de clases de la solución propuesta - Diagramas de clases utilizando UML con el nombre de la clase y los nombres de atributos y métodos de cada una. - Descripción de cada clase incluyendo sus métodos y atributos con las descripciones respectivas, al igual que las responsabilidades de la clase. Por ejemplo: puede crearse la estructura general de la aplicación y luego generar la documentación con alguna herramienta similar a “javadoc”. - Diseño de pantallas y diagrama de navegación de la aplicación. - Descripción de algoritmos complejos en pseudo-código identificando la clase y métodos involucrados. 6. Manual de usuario con las pantallas reales Este es un instructivo que explica paso a paso las opciones presentes en el programa y las acciones que llevará a cabo el mismo en cada caso. Las pantallas pueden ser capturadas con las teclas ALT-ImprimirPantalla mientras ejecuta su programa. 7. Casos de prueba que se le presentarán al programa Se debe presentar una lista con la descripción y los resultados esperados de los casos de prueba que se le presentaran al programa para asegurarse que el mismo cumple con lo especificado. La lista de casos de prueba debe ser diseñada previamente o durante la elaboración del programa de manera que una vez terminado el mismo se pueda evaluar el resultado obtenido en cada punto. Cada caso debe tener como mínimo una descripción del mismo, el objetivo de la prueba, y los valores de entrada y la salida o resultado esperado. En caso de trabajos en grupo es conveniente que exista un responsable de la elaboración de los casos de prueba y de la evaluación de los resultados a modo de asegurador de la calidad. Dicho estudiante puede hacerse responsable de asegurarse de la calidad del código fuente que se produce tal y como se presenta en el punto 10. 8. Resultados de los casos de prueba Aquí se debe presentar una descripción puntual y llana de los resultados obtenidos. Simplemente que es lo que se esperaba en el caso de prueba y que es lo que se obtuvo. No deben darse juicios de valor en este punto. Dichas valoraciones deben dejarse para la siguiente sección. Esta sección puede ser llevada a cabo por un solo miembro del grupo mientras que el análisis debe ser el producto de la discusión entre los miembros del grupo y el estudio del código. 9. Análisis de los resultados de las pruebas En este punto se deben incluir las explicaciones y sugerencias que surjan como producto de los resultados obtenidos por las pruebas a su programa. Puede incluir desde razonamientos por las posibles causas de errores presentados. O bien incluir propuestas para mejorar el programa existente en cuanto a eficiencia. En caso de existir errores en tiempo de ejecución, debe listarlos y mencionar sus posibles causas y su análisis sobre la causa o posibles soluciones alternas. Es conveniente identificar el punto desde el cual se viene arrastrando el error. Por ejemplo: Si fue un error en la interpretación inicial del problema, en el análisis o diseño del mismo, o si se debe a problemas en la codificación de lo planteado. 10. Código fuente impreso con su respectiva documentación interna El código fuente debe cumplir con los criterios mínimos referentes a una buena documentación interna. Aquí debemos incluir los aspectos básicos de legibilidad y claridad en el código hasta la especificación apropiada mediante el uso de comentarios internos y nombres significativos. Debe incluir lo siguiente como mínimo: - Alineamiento apropiado entre las líneas de código que se encuentran a cada nivel de anidamiento. (Algunos se refieren a esto como Tabulación o Indentación apropiada) - Nombres de variables en minúscula. Por ejemplo: saldoDeCuenta - Nombres de constantes en mayúscula. Por ejemplo: CANTIDAD_MAXIMA_DE_USUARIOS - Nombres de Clase en iniciando con la primera letra en mayúscula. Por ejemplo: Estudiate - Nombres significativos. Por ejemplo: saldoDeCuentaCorriente, en lugar de la palabra dinero - Iniciar cada palabra significativa con mayúscula cuando se tengan nombres compuestos por varias palabras, o separados por el carácter “_” en caso de constantes. Por ejemplo: saldoDeCuentaCorriente o bien CANTIDAD_MAXIMA_DE_USUARIOS - Uso de comentarios para explicar el uso de identificadores importantes - Uso de comentarios para documentar la especificación de cada Clase y funcionalidad de sus métodos, incluyendo descripción de parámetros y valores de retorno en cada uno. - Uso de comentarios con pseudo-código o justificación con respecto a la escogencia de una implantación versus otra en caso de eficiencia. B. ASPECTOS ETICOS Y DERECHOS DE AUTOR Normas para el uso Justo de la Organización Mundial del Comercio OMC ARTICULO 107 - El artículo plantea 4 factores: Los materiales con derechos de autor pueden ser utilizados sin permiso expreso del dueño respetando las siguientes condiciones. - Uso educacional-no lucrativo. - Índole de la obra con derechos. - Fragmentos de la obra. - No debe perjudicar comercialmente al autor. Normas para el uso justo Extensión de las obras: artículo de 1000 palabras, 1 ilustración, tabla o gráfica, poner fuente, películas 3 minutos, música 30 segundos y 5 fotos. Aunque se pretende que se dé un intercambio de ideas en cuanto a las formas de solución de un problema, eso no es lo mismo que compartir código fuente. La Universidad de Costa Rica cuenta con el Reglamento Estudiantil donde se especifican las penas a que se someterá un estudiante o grupo de estudiantes en caso de copia o intento de engaño. Para evitar problemas recuerde lo siguiente, en casos donde se utiliza una idea ajena (Incluyendo desde el uso de alguna herramienta, diagrama, texto, algoritmo o código que se utilice para mejorar la calidad del trabajo o para facilitar el mismo y siempre que sea permitido en el contexto del problema) SIEMPRE debe agregarse una referencia al autor del mismo y a la fuente bibliográfica o documental de donde se obtuvo. En ningún se podrá copiar código fuente externo para ser entregado como propio. En este curso de programación el hecho de tomar código con soluciones a problemas bajadas de Internet o copiadas de otro grupo o compañero está prohibido. Además, se debe tomar en cuenta que todos los problemas siempre presentan pequeños matices que concluyen en múltiples posibles soluciones al mismo por lo que no pueden existir dos soluciones idénticas a un mismo problema. Siempre, el evaluador de las tareas programadas llevará a cabo una evaluación individualizada para detectar posibles fraudes en caso de existir alguna duda. C. EVALUACION Se evaluará su trabajo de acuerdo a la siguiente plantilla: EVALUACION DE TAREA / O / / / / O / / T / / R / / J / / L / / A / / A / / A / / L / / B / / / O / U / O / / / Y / T / G / J / Y / / U / L / E / A / U / DOCUMENTACION INTERNA / M / A / R / B / M / -----------------------------------------+---+---+---+---+---+ Tabulación y anidamiento correcto | 8 | 6 | 4 | 2 | 0 | -----------------------------------------+---+---+---+---+---+ Nombres significativos | 8 | 6 | 4 | 2 | 0 | -----------------------------------------+---+---+---+---+---+ Usa comentarios para especificar | 8 | 6 | 4 | 2 | 0 | variables, métodos, parámetros y clases | | | | | | -----------------------------------------+---+---+---+---+---+ Consistencia en uso de convenciones | 6 | 4 | 2 | 1 | 0 | de programación | | | | | | -----------------------------------------+---+---+---+---+---+ LOGICA DEL CODIGO FUENTE -----------------------------------------+---+---+---+---+---+ Claro | 15| 10| 6 | 3 | 1 | -----------------------------------------+---+---+---+---+---+ Modular | 15| 10| 6 | 3 | 1 | -----------------------------------------+---+---+---+---+---+ EJECUCION -----------------------------------------+---+---+---+---+---+ Compila y ejecuta sin errores de sintaxis| 10| 6 | 3 | 1 | 0 | -----------------------------------------+---+---+---+---+---+ Soluciona correctamente el problema | 15| 10| 6 | 3 | 1 | -----------------------------------------+---+---+---+---+---+ Casos de prueba apropiados | 15| 12| 9 | 6 | 3 | -----------------------------------------+---+---+---+---+---+ FACTOR DE COMPLETITUD (multiplique por) |1.0|0.8|0.6|0.4|0.2| -----------------------------------------+---+---+---+---+---+ TOTAL D. FORMA DE ENTREGA La ley costarricense indica que solo los documentos impresos tienen calidad de prueba por lo que (salvo una contraindicación por parte de su instructor el cual podría aceptar un archivo en formato no modificable PDF debidamente firmado vía e-mail) la documentación debe presentarse impresa en sobre manila. El código fuente debe presentarse en formato electrónico (archivos de texto .h y .cpp). Y la documentación en formato HTML. Puede ser entregado vía CD, o colocándolo en alguna carpeta o repositorio previamente establecido para el material del curso.