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.

Documentación de Código:¿Qué, cómo, por qué?

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ú.