Las mejores APIs parecen obvias en retrospectiva. Llamas a un método, hace la única cosa que su nombre promete y se sigue comportando así a lo largo de una docena de versiones. Esa fiabilidad no es suerte. Es el resultado de un puñado de decisiones tomadas temprano y defendidas con el tiempo.

## Nombra las cosas para quien las llama, no para la implementación

Una API es una promesa escrita en nombres de métodos. Cuando nombras una función según cómo funciona internamente, cada refactorización amenaza con romper esa promesa. Nómbrala según lo que quiere quien la llama, y la implementación queda libre para cambiar por debajo.

La prueba es simple: lee el lugar de la llamada en voz alta. Si un nuevo compañero de equipo puede adivinar qué ocurre sin abrir el código fuente, el nombre está cumpliendo su función.

## Haz que el caso común sea sin esfuerzo

La mayoría de quienes llaman quieren lo mismo la mayor parte del tiempo. Diseña la ruta por defecto para que no requiera configuración, y luego añade opciones por encima para los casos raros. Una API que exige cinco parámetros para una tarea rutinaria será envuelta en un ayudante por el primer equipo que la use, y ahora mantienes dos interfaces en lugar de una.

> Cada argumento obligatorio es un pequeño impuesto que cobras en cada llamada. Cóbralo solo cuando el valor genuinamente no pueda inferirse.

## Versiona el contrato, no el código

Los cambios que rompen la compatibilidad no son el enemigo. La sorpresa sí lo es. Cuando debas romper algo, dale un nuevo nombre o una nueva versión y deja que la ruta antigua siga funcionando durante una ventana de obsolescencia clara. Quienes llaman perdonarán una migración que puedan planificar. No perdonarán un cambio silencioso que rompe la producción un martes.

Una API que envejece bien es una en la que puedes dejar de pensar. Constrúyela de modo que quienes dependen de ella también puedan hacerlo.

Diseñar APIs que envejecen bien

Nadie agenda una reunión sobre los tiempos de compilación. Van creciendo de una dependencia en una dependencia hasta que una recompilación completa dura lo suficiente para justificar mirar el teléfono. Esa pausa parece inofensiva. No lo es.

## El contexto es lo que en realidad pierdes

Cuando una compilación tarda treinta segundos, te quedas dentro del problema. Cuando tarda tres minutos, te vas. Cambias de pestaña, lees un mensaje, sigues un enlace, y para cuando la compilación termina tienes que reconstruir el modelo mental que acabas de soltar. El costo en tiempo de reloj es de minutos. El costo real es la recarga.

## Las compilaciones lentas cambian el comportamiento

Los equipos se adaptan a la retroalimentación lenta de maneras que empeoran el código. Agrupan cambios sin probar porque ejecutar el ciclo es costoso. Se saltan la pequeña refactorización porque no vale la pena esperar otra vez. Dejan de escribir el experimento rápido que habría respondido una pregunta con código en lugar de con un debate.

> La velocidad de tu ciclo de retroalimentación fija el tamaño del cambio más pequeño que alguien está dispuesto a hacer.

## Trátalo como una métrica de primera clase

Mide el tiempo de compilación y de pruebas como mides el tiempo de actividad. Ponlo en un panel. Establece un presupuesto y defiéndelo en las revisiones. Cuando un cambio empuja la compilación más allá del presupuesto, ese es un costo real que sopesar, no un error de redondeo que ignorar.

Las compilaciones rápidas no son un lujo para equipos grandes. Son la base que permite a un equipo pequeño seguir moviéndose como un equipo pequeño.

El costo real de una compilación lenta

Pregúntale a un ingeniero cómo mejora y te hablará de escribir más código, hacer proyectos paralelos, aprender un nuevo lenguaje. Casi nadie dice que practica la lectura. Sin embargo, en cualquier equipo real, leer es el trabajo. Lees para revisar, para depurar, para entender lo que estás a punto de cambiar.

## Empieza por la forma antes que por los detalles

Cuando abres un archivo desconocido, resiste el impulso de leerlo de arriba abajo. Primero echa un vistazo a la estructura. ¿Cuáles son las exportaciones principales? ¿Por dónde entran los datos y por dónde salen? Un mapa rápido de la forma hace que los detalles aterricen en algún lugar en vez de amontonarse.

## Sigue una ruta de principio a fin

Elige un único escenario realista y trázalo de extremo a extremo. Una petición, un clic, una entrada. Seguir una ruta concreta enseña más que leer cada rama, porque muestra lo que realmente ocurre en lugar de todo lo que podría ocurrir.

> No entiendes un sistema hasta que puedes predecir qué hará con una entrada que nunca has visto.

## Lee a propósito código que admiras

Reserva tiempo para leer una biblioteca bien construida como estudiarías buena escritura. Fíjate en cómo nombra las cosas, dónde traza los límites, qué eligió no hacer. Absorberás patrones a los que podrás recurrir más adelante sin tener que reinventarlos bajo presión.

Leer no es la parte pasiva de la ingeniería. Es donde ocurre en realidad la mayor parte de la comprensión. Dale la misma práctica deliberada que le das a todo lo demás, y escribir también se vuelve más fácil.

Ingeniería

Diseñar APIs que envejecen bien

El costo real de una compilación lenta

Leer código es una habilidad que puedes practicar