Archivo de la etiqueta: documentación

Explicando código con arte ASCII

Aquí hay otro ejemplo de cómo la documentación aumenta el valor de tu código. John Regehr recopiló imágenes de cómo en algunos proyectos de código abierto se usa arte ASCII para explicar el código de manera más clara.

En su artículo, escribe:

Las personas tienden a ser visuales: usamos imágenes para entender problemas. Los lenguajes de programación más populares, por el contrario, operan en un espacio completamente abstracto, dejando una gran brecha entre programa e imagen.

Un ejemplo tomado del compilador de Swift:

Puedes utilizar apps como Mondraw para crear este tipo de documentación. Recuerda el Triángulo de la Documentación de Código, y que agregar documentación no es una admisión de que no fuiste lo suficientemente inteligente para escribir “buen” código.

 

El Triángulo de la Documentación de Código

Hace un tiempo propuse que deberías escribir código que se documente solo, y luego agregarle documentación. En el artículo original, escribí:

La idea de que “tu código debería de documentarse solo” no es un get out of jail free card para no documentar tu código. Las ocasiones en tu carrera profesional donde escribir documentación no agrega valor a tu trabajo son muy pocas. Tan pocas, de hecho, que no se me viene ninguna a la mente. ¿Tal vez cuando estás trabajando en un proyecto propio? Pero hasta Damian Conway dijo que “la documentación es una carta de amor que le escribes a tu yo del futuro”.

Hoy me encontré una idea que aumenta mi punto: El Triángulo de la Documentación de Código.

Este modelo mental nos dice que toda pieza de código está documentada en 3 dimensiones distintas, cada una respondiendo una pregunta muy particular.

  • ¿Qué?: Tu código, en sí, explica lo que estás haciendo.
  • ¿Por qué?: Los comentarios que le agregas a tu código, explican tu proceso de toma de decisiones y la razón de tus soluciones.
  • ¿Cómo?: El contexto dentro del cual estás desarrollando tu programa; la descripción original del problema.

Si te enfocas en escribir código que “se documente solo”, en un futuro no sabrás por qué llegaste a esa solución, ni cómo esa solución es apropiada para el problema original.

Recuerda, agregar documentación a tu código (en forma de comentarios, glosarios, RFCs, pruebas, etc.), no es una admisión que no fuiste lo suficientemente inteligente para escribir “buen” código, sino un acto de compasión. Demuestra tu interés porque la siguiente persona que modifique tu código pueda enfocarse en agregar valor al proyecto — y, muy probablemente, esa siguiente persona vas a ser tú.

Haz código que no necesite documentación. Y documéntalo.

Los programadores tenemos tendencias egocéntricas.

Entendemos (o creemos entender) cómo funcionan las computadoras. Y eso nos hace sentir especiales. Y si somos tan especiales para entender cómo funcionan las computadoras, cualquier persona que no entienda mi código no es tan especial como yo.

Documentar qué estás haciendo, y por qué, puede ser un golpe al ego. Pero uno que vale la pena. Que documentes algo no es una admisión que no fuiste lo suficientemente inteligente para escribir “buen” código, sino un acto de compasión. Demuestra tu interés porque la siguiente persona que modifique tu código pueda enfocarse en agregar valor al proyecto — y muy probablemente esa siguiente persona seas tú.

La idea de que “tu código debería de documentarse solo” no es un get out of jail free card para no documentar tu código. Las ocasiones en tu carrera profesional donde escribir documentación no agrega valor a tu trabajo son muy pocas. Tan pocas, de hecho, que no se me viene ninguna a la mente. ¿Tal vez cuando estás trabajando en un proyecto propio? Pero hasta Damian Conway dijo que “la documentación es una carta de amor que le escribes a tu yo del futuro”.

Escribir documentación no tiene que ser aburrido ni estar limitado a únicamente escribir comentarios.

En orden de accesibilidad, puedes escribir:

  1. comentarios en tu código.
  2. READMEs
  3. glosarios
  4. RFCs o documentos de diseño
  5. pruebas
  6. Documentos de arquitectura

Te invito a que veas la documentación como un tema de accesibilidad, y no de exactitud. ¿Qué opinarías de alguien que dice que no debería haber rampas en las banquetas de una ciudad porque no necesita caminar para transportarse? Reflexiona.