11.4. Documentación básica de programas
La mayor parte de la documentación de un programa "serio" se debe realizar antes de comenzar a teclear:
- Especificaciones de requisitos, que reflejen lo que el programa debe hacer.
- Diagramas de análisis, como los diagramas de casos de uso UML, para plasmar de una forma gráfica lo que un usuario podrá hacer con el sistema.
- Diagramas de diseño, como los diagramas de clases UML que vimos en el apartado 6.4, para mostrar qué tipos de objetos formarán realmente nuestro programa y cómo interactuarán.
- …
Casi todos esos diagramas caen fuera del alcance de este texto: en una introducción a la programación se realizan programas de pequeño tamaño, para los que no es necesaria una gran planificación.
Aun así, hay un tipo de documentación que sí debe estar presente en cualquier problema: los comentarios que aclaren todo aquello que no sea obvio.
Por eso, este apartado se va a centrar en algunas de las pautas que los expertos suelen recomendar para los comentarios en los programas, y también veremos como a partir de estos comentarios se puede generar documentación adicional de forma casi automática.
11.4.1. Consejos para comentar el código
Existen buenas recopilaciones de consejos en Internet. Yo voy a incluir (algo resumida) una de José M. Aguilar, recopilada en su blog "Variable not found". El artículo original se puede encontrar en:
http://www.variablenotfound.com/2007/12/13-consejos-para-comentar-tu-cdigo.html1. Comenta a varios niveles
Comenta los distintos bloques de los que se compone tu código, aplicando un criterio uniforme y distinto para cada nivel, por ejemplo:
- En cada clase, incluir una breve descripción, su autor y fecha de última modificación
- Por cada método, una descripción de su objeto y funcionalidades, así como de los parámetros y resultados obtenidos
(Lo importante es ceñirse a unas normas y aplicarlas siempre).
2. Usa párrafos comentados
Además, es recomendable dividir un bloque de código extenso en "párrafos" que realicen una tarea simple, e introducir un comentario al principio además de una línea en blanco para separar bloques: