Desarrollo de Software

La importancia de una buena documentación interna

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:

Elección de nombres significativos

La elección de nombres significativos para los identificadores (tanto de constantes, como variables, funciones…) es crucial para que un programa sea inteligible.

Consideremos las siguientes sentencias

e = v * t
espacio = velocidad * tiempo

La primera de las sentencias es más concisa, pero la segunda aporta mucha más información al lector de la misma.

El nombre de los identificadores debe elegirse de forma que no deje lugar a duda sobre su objetivo o el significado del valor que va a contener.

Comentarios

La posibilidad de expresar comentarios en lenguaje natural como parte del listado del código fuente es algo que aparece en todos los lenguajes de programación. Los comentarios permiten al programador comunicarse con otros lectores del código, resultando una clara guía de comprensión durante las etapas de mantenimiento.

Se pueden distinguir, básicamente, dos tipos de comentarios: Iniciales o de prólogo y descriptivos.

Los comentarios de prólogo deben aparecer al principio de cada programa o subprograma. Estos comentarios sirven para describir clases, propiedades, funciones, etc.

Los comentarios descriptivos se insertan dentro del código para explicar algún trozo complicado de éste.

Hay que advertir que los comentarios deben contribuir a aclarar el significado del programa. Los comentarios que se limitan a parafrasear el código, como «sumar var1 y var2», suelen ser superfluos y sólo sirven para hacerlo más ilegible y aumentar el tamaño de los archivos.

Indentación

La forma en que el código fuente aparece en el listado supone una importante contribución a la legibilidad del mismo. La indentación o sangrado del código realza las construcciones lógicas y los bloques del código.

No es lo mismo:

#include <stdio.h>
 
int main ()
{
int i, j;
for (i=0;i<=10;i++)
for (j=0;j<=10;j++)
printf("%i x %i = %in", i, j, i*j);
return 0;
}

que

#include <stdio.h>
 
int main ()
{
   int i, j;
   for (i=0;i<=10;i++)
      for (j=0;j<=10;j++)
         printf("%i x %i = %in", i, j, i*j);
 
   return 0;
}

aunque ejecute lo mismo. El segundo trozo de código es más legible que el primero. Y se trata de un pequeño ejemplo, imagínate varios cientos de líneas.

Espero que con este artículo se haya entendido un poco por qué es mejor «perder» un poco más de tiempo en la implementación del código de un programa creando una buena documentación interna que hacerlo después (y mucho más tiempo) en una posible modificación o estudio del código.

En un próximo post haré una lista de ciertas reglas que suelo utilizar en la documentación interna de los proyectos que desarrollo.

Un comentario en “La importancia de una buena documentación interna

  1. Comentario
    Buena forma de recordar los principios de «C++»
    Principios que tambien se aplican a HTML
    que como puedes ver no estoy practicando ya que en HTML es menos riguroso.Aunque si estoy de acuerdo en que es mas legible cuando se usa el sangrado

Pon un comentario

Tu dirección de email no será publicada.

Puedes usar estas etiquetas y atributos HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>