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.
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.
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.
·
Descripción
del resto del trabajo.
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.
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.
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.
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.
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.
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.
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: Estudiante.
·
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.