Haz código que no necesita 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:
- comentarios en tu código.
- READMEs
- glosarios
- RFCs o documentos de diseño
- pruebas
- 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.