«Creo que funciona así» es una frase que en un proyecto de software se paga más tarde. Las bibliotecas cambian, las funciones se deprecan, y el código escrito de memoria arrastra los patrones de hace tres versiones. El desarrollo guiado por las fuentes propone una regla sencilla: toda elección que dependa de un framework se apoya en su documentación oficial, y lo dice.
El proceso
1. Detectar la pila y las versiones. Antes de escribir código se leen los archivos de dependencias del proyecto (por ejemplo los que enumeran paquetes y versiones). Una regla vale para una versión: sin saber cuál, no se sabe si es correcta.
2. Leer la documentación oficial. Para la función que hace falta, se consulta la documentación del framework para la versión en uso, no un artículo de blog ni una respuesta de un foro. Si no se encuentra la versión exacta, se declara.
3. Seguir los patrones documentados. Se implementa como indica la documentación, incluso cuando la memoria sugiere otro camino. Si se decide apartarse, se explica por qué.
4. Citar las fuentes. Cada decisión específica del framework lleva su referencia (el enlace a la página) junto al código o en la descripción del cambio. Así quien revisa puede verificarlo en un minuto, y quien lo lea dentro de un año sabe de dónde viene la elección.
Por qué hace falta
Los asistentes y las personas comparten un límite: recuerdan la versión que más han visto, no la que usa el proyecto. La API deprecada que aparece por todas partes en los tutoriales es la que se reescribe varias veces. Una fuente oficial y fechada convierte una opinión en un hecho comprobable.
Las excusas más comunes
| Excusa | Realidad |
|---|---|
| «Conozco bien esta biblioteca» | ¿Qué versión? Las interfaces cambian, y la memoria es de otra. |
| «Buscarlo lleva un segundo, pero sigo mientras tanto» | La búsqueda cuesta menos que una reescritura. |
| «Un tutorial lo dice» | Un tutorial es una fuente secundaria, a menudo de otra versión. |
Señales de alarma
- Código específico de un framework escrito sin comprobar la documentación de la versión en uso.
- Frases como «creo» o «me parece» sobre una API en lugar de una fuente citada.
- Un patrón implementado sin saber a qué versión se aplica.
- Foros y blogs citados en lugar de la documentación oficial.
- API deprecadas usadas porque aparecen a menudo.
- Ninguna lectura de los archivos de dependencias antes de escribir.
- Código entregado sin referencias a fuentes para las elecciones ligadas al framework.
Un ejemplo
Hay que gestionar la carga de datos en un componente de un framework. En el archivo de dependencias se lee que la versión es la 5; la documentación de la 5 indica una forma distinta de la 4, que todavía se cita mucho en línea. Se usa la de la 5 y en la descripción del cambio se añade el enlace a la página. Quien revisa lo comprueba en un minuto.
Cuándo usarlo
Cuando se quiere código con fuentes verificables y libre de patrones obsoletos; al trabajar con cualquier framework o biblioteca donde la corrección importa.
Este método deriva de la familia de skills de código abierto agent-skills de Addy Osmani (licencia MIT), reescrita y adaptada.
Este artículo es una skill de OIAR
Lo que acabas de leer es el contenido de una skill del catálogo de OIAR, escrito para las personas. Un conocimiento como este pero más rico y profundo, escrito para los agentes, guía las entrevistas, el análisis y el informe dentro de la plataforma. Las skills se usan en OIAR: para probarla en un proyecto tuyo necesitas una cuenta.
source-driven-developmentMétodo para basar cada elección de framework o biblioteca en la documentación oficial de la versión en uso: detectar la pila, leer la fuente, seguir los patrones documentados, citar las referencias. Úsese al escribir código con frameworks o bibliotecas donde la corrección importa o se sospechan patrones obsoletos.