Archivo de la etiqueta: 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ú.

Analogías, principios básicos y modelos mentales para resolver problemas

Aprende a buscar analogías y modelos mentales que te ayuden a razonar mejor las soluciones que propones.

Regresa a los principios básicos de cómo se resuelven diferentes tipos de problemas, y extrapola sobre eso para tu caso de uso particular. Por ejemplo, si necesitas crear un sistema para que usuarios suban y validen documentos, analiza cómo lo resolvieron en 1989 con el protocolo HTTP. Construye sobre ese principio.

La gran mayoría de problemas que te va a tocar resolver en tu carrera no son nuevos. Y muchas de las dificultades técnicas con las que te vas a enfrentar vendrán de tu propia renuencia a levantar la cabeza para buscar soluciones externas, y de tu tendencia de reinventar la rueda cada vez.

Estás construyendo sobre los hombros de gigantes. Aprovéchalo.

Los desarrolladores ya no se preocupan por la fiabilidad de su software

Buen rant sobre el estado actual de muchos proyectos de software.

Todos hemos sentido esa desesperación de intentar enviar una forma en una página web y que, por alguna razón, falle con errores crípticos. Para muchas personas, una solución aceptable es recargar la página.

Como personas que desarrollan software, estamos acostumbrados a pensar de manera lógica, tomando en cuenta el estado del programa para saber si deberíamos presionar o no algún botón. Pero como usuarios, estamos tan acostumbrados a lidiar con software hecho lo más rápido posible para ser el primero en el mercado, que hemos normalizado darle la vuelta a estos problemas de maneras completamente inaceptables.

¿Ya lo apagaste y volviste a prender?

El autor cierra el rant con lo siguiente:

Finalmente, deja que el dinero defina todo lo que haces. Sí, los desarrolladores tienen el tiempo contado y ese tiempo cuesta. Sí, los usuarios con necesidades molestas como accesibilidad e internalización son más caros de soportar que los retornos de inversión que generan. Pero lo tienes que pagar de todos modos. Es lo correcto. Podemos generar ganancias y ser empáticos. No pienses en ser el primero en el mercado, y mejor prioriza tener un buen producto para ofrecerle a tus clientes. Nuestros usuarios no son ganado. No es nuestro trabajo convertir su atención en dinero a su costa. Necesitamos tratar a nuestros usuarios con respeto, y eso significa probar nuestro código antes de mandarlo a producción.

?

Enlace: https://drewdevault.com/2021/10/17/Reliability.html