La documentación interna de un programa incluye elementos cuyo objetivo es facilitar la inteligibilidad del mismo.
Pero, ¿qué más da que el programa pueda entenderse o no si funciona correctamente? Los programas, a veces, son estudiados y modificados por personas distintas de las que originalmente la crearon, por lo que la legibilidad de un programa es un punto importante. No es lo mismo tardar 5 minutos en entender un código que tardar un par de horas en intentar saber que es lo que hace porque no tiene unos buenos comentarios y no está correctamente estructurado. El ahorro de tiempo es increíble.
Además, la mayoría de las aplicaciones se llevan a cabo por parte de un equipo. Una buena documentación interna del código que se esté desarrollando favorece la comunicación entre los distintos miembros del equipo, mejorando su productividad. Es más, si por cualquier causa (baja, despido, etc.) hay que integrar un nuevo miembro al equipo, a éste le costará mucho menos con un código mucho más legible.
Pero una buena documentación interna no sólo va a ayudar al resto de personas a entender tu código, sino que a ti también te puede resultar beneficioso. Imagínate que hace unos meses creaste una clase en, por ejemplo, ActionScript que creaba una galería de imágenes muy guapa con un montón de efectos y transiciones que te quedo muy bien. Ahora, unos meses después, quieres modificar la clase para poder incluir una pequeña descripción a cada foto. Y no te acuerdas como lo hiciste. ¿No será más fácil “recordar” el código teniendo unos buenos comentarios y una buena estructura que tener varios cientos de líneas de código teniendo que descifrar para que se utilizan unos atributos y otros? Lo que quizás no te llevara más de media hora te puede costar una tarde entera.
Los tres elementos más significativos de la documentación interna son la elección de nombres significativos, los comentarios y la indentación. Veremos, a continuación, cada uno de ellos:
Seguir leyendo "La importancia de una buena documentación interna"