Resumen: Entrega nº48 del curso Bases de la programación Nivel II.
Codificación aprenderaprogramar.com: CU00249A

 

 

MEJORAS FINALES. DOCUMENTACIÓN DEL PROGRAMA.

Nuestro automóvil está listo. Nos falta atar con una cinta unos cables sueltos, separar dos mangueras que están entrelazadas y elaborar dos documentos a partir de toda la información disponible: el manual del usuario y el manual del mecánico.

 

Anagrama aprenderaprogramar.com

 

Nuestro programa está listo. Nos falta dar los últimos retoques a la presentación del código, ese módulo que ha quedado con las sangrías desordenadas, introducir algunas líneas en blanco para facilitar la lectura, esos archivos sueltos que vamos a dejar ordenados en directorios... Así como elaborar dos documentos a partir de toda la información disponible: el manual del usuario y el manual de mantenimiento, o si se prefiere, documentación para el usuario y documentación para el mantenimiento. Al igual que en un coche nos hace falta el manual para saber qué hace tal botón o cómo desmontar tal pieza, es necesario dejar documentación que nos informe del funcionamiento y posibilidades del programa así como de su estructura de cara al mantenimiento.

Terminada la mejora estética y antes de preparar la documentación conviene realizar las mejoras finales:

 

1.- Mejora de la presentación del código y sus comentarios.

Muchas veces durante el desarrollo del programa hacemos comentarios abreviados o poco explícitos. Conviene reemplazar aquellos comentarios poco entendibles por otros claros y fáciles de entender.

Por ejemplo [Si a negativo peligro saltamos]

Cambiarlo por [Si a es negativo imposible calcular su raíz cuadrada. En este caso saltamos al módulo Transforma]

 

En otras ocasiones hay partes del código que se utilizaron para una verificación y que hay que eliminar en la versión definitiva del programa. Puede ocurrir que hasta el momento final hayamos estado haciendo verificaciones y tengamos el código de la verificación como comentario. Igualmente conviene eliminarlo: el programa ha de quedar limpio.

Ejemplo:

Mostrar a : Mostrar b

Mostrar m : Mostrar n

Mostrar i : Mostrar j

Mostrar A

Desde i = a hasta b Hacer

Desde j = m hasta n Hacer

A = i * j

Mostrar A

Siguiente j

Siguiente i

  ====>  

Desde i = a hasta b Hacer

Desde j = m hasta n Hacer

A = i * j

Mostrar A

Siguiente j

Siguiente i

Código contaminado por una verificación de variables y contadores   Código limpio

 

Desde i = a hasta b Hacer

[Mostrar i]

PEC = i * b

Mostrar PEC

Siguiente

  ====>  

Desde i = a hasta b Hacer

PEC = i * b

Mostrar PEC

Siguiente

Código contaminado por comentario transitorio no útil, en este caso un seguimiento de un contador conservado como comentario.   Código limpio

 

 

La presentación del código se revisa y mejora para facilitar su lectura, como si de un texto se tratase.

Ejemplo:

Si FOM > FUM Entonces

Mostrar A

Mostrar B

Mostrar C

FinSi

Si FEM > FUM Entonces

Mostrar FEM

FinSi

====>  

Si FOM > FUM Entonces

Mostrar A

Mostrar B

Mostrar C

FinSi

Si FEM > FUM Entonces

Mostrar FEM

FinSi

    Se revisa en cuanto a sangrías, separación entre bloques, etc

 

 

2.- Organizar los módulos.

Si existen módulos muy interrelacionados que se encuentran distanciados, convendrá agruparlos para facilitar la lectura y comprensión del programa. Igualmente el orden en que aparecen los módulos se intentará que sea lo más aproximado a la forma de ejecución del programa.

 

3.- Mejorar el diagrama de flujo.

Si existe un diagrama de flujo, mejoramos igualmente su presentación: tamaño de letra y elementos gráficos adecuados, separación entre elementos adecuada, reorganización de páginas para evitar excesivos apelotonamientos o espacios en blanco, etc.

 

4.- Actualizar el esquema descendente o índice descendente.

Comprobar que el esquema descendente refleje la estructura última del programa, incluyendo los últimos cambios que haya habido, y que su presentación es clara y correcta.

 

5.- Organizar los archivos.

Si el programa consta o usa varios archivos, estos deberán quedar bien ordenados en directorios con nombres descriptivos que permitan una fácil localización y entendimiento del contenido.

 

Terminado este proceso de “pulimento” tenemos un producto que funciona, de agradable estética, ordenado y organizado. Sobre él podemos desarrollar la documentación del programa. En realidad debemos decir la documentación externa del programa, ya que el programa en sí mismo contiene información equivalente a documentación en forma de nombres descriptivos de variables, nombres descriptivos de módulos, comentarios, organización y claridad. A todo ello lo llamamos documentación intrínseca, interna o autodocumentación. La documentación interna es de gran importancia y no debe descuidarse pensando que con un buen manual de mantenimiento todo queda resuelto.

Podemos considerar una buena práctica de programación apoyar la facilidad de lectura y comprensión del programa en todas sus vertientes. No debemos sustituir información básica como el nombre descriptivo para una variable o módulo por un comentario que es información accesoria. Tampoco debemos sustituir un comentario necesario por una extensa y prolija explicación en un manual.

 

 

 

 

 

 

Para acceder a la información general sobre este curso y al listado completo de entregas pulsa en este link:  Ver curso completo.

Para  hacer un comentario o consulta utiliza los foros aprenderaprogramar.com, abiertos a cualquier persona independientemente de su nivel de conocimiento.

Descargar archivo: