Formas y técnicas de documentar algoritmos y programas.
Documentar el código de un programa es añadir suficiente información como para explicar lo que hace, punto por punto, de forma que no sólo los ordenadores sepan qué hacer, sino que además los humanos entiendan qué están haciendo y por qué.
Documentar un programa no es sólo un acto de buen hacer del programador por aquello de dejar la obra rematada. Es además una necesidad que sólo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el programa con nuevas capacidades o adaptarlo a un nuevo escenario. Hay dos reglas que no se deben olvidar nunca:
1. todos los programas tienen errores y descubrirlos sólo es cuestión de tiempo y de que el programa tenga éxito y se utilice frecuentemente
2. todos los programas sufren modificaciones a lo largo de su vida, al menos todos aquellos que tienen éxito
Por una u otra razón, todo programa que tenga éxito será modificado en el futuro, bien por el programador original, bien por otro programador que le sustituya. Pensando en esta revisión de código es por lo que es importante que el programa se entienda: para poder repararlo y modificarlo.
¿Qué hay que documentar?
Hay que añadir explicaciones a todo lo que no es evidente.No hay que repetir lo que se hace, sino explicar por qué se hace.
Y eso se traduce en:‡ ¿de qué se encarga una clase? ¿un paquete?‡ ¿qué hace un método?‡ ¿cuál es el uso esperado de un método?‡ ¿para qué se usa una variable?‡ ¿cuál es el uso esperado de una variable?‡ ¿qué algoritmo estamos usando? ¿de dónde lo hemos sacado?‡ ¿qué limitaciones tiene el algoritmo? ¿... la implementación?‡ ¿qué se debería mejorar ... si hubiera tiempo
No hay comentarios:
Publicar un comentario