L'interfaccia è il contratto

La riga di codice più costosa che cambierai mai non è nell'implementazione. È nella firma del tipo.

Puoi rinominare una variabile, sostituire un algoritmo, riscrivere una query — finché l'interfaccia rimane invariata, niente si rompe. L'interfaccia è la promessa. L'implementazione è il modo in cui la mantieni.

Contratti impliciti ed espliciti

Ogni funzione ha un contratto: dati questi input, produci questo output, in queste condizioni. In JavaScript non tipizzato, quel contratto vive nella tua testa, in commenti, forse in documentazione che nessuno legge. Può derivare. Può essere sbagliato. Può semplicemente non esistere.

TypeScript rende i contratti di prima classe. Quando definisci una firma di funzione, non stai solo annotando — stai pubblicando una promessa che il compilatore farà rispettare. Il beneficio più grande non è intercettare errori di tipo al punto di chiamata. È che non puoi cambiare casualmente un contratto senza che il compilatore ti mostri ovunque quella modifica abbia importanza.

Prima l'interfaccia

La disciplina che ho trovato più utile: prima di scrivere l'implementazione, scrivi la firma del tipo. Cosa riceve questa funzione? Cosa restituisce? Quali sono gli invarianti?

Suona come design-up-front, che ha una cattiva reputazione per buone ragioni. Ma una firma di tipo non è una spec — è una riga. Scriverla prima ti costringe a pensare a come il codice verrà usato prima di pensare a come funzionerà. Sono domande diverse, e la prima è quasi sempre più importante.

Quando ho costruito la logica di prenotazione per Barba Studio, ho scritto le firme di funzione per il layer di scheduling prima di toccare il database. Non per rigore — perché avevo bisogno di capire cosa aveva effettivamente bisogno di chiamare l'UI. L'implementazione è cambiata diverse volte. L'interfaccia quasi per niente.

Il gradiente di stabilità

Non tutte le interfacce sono ugualmente costose da cambiare. C'è un gradiente naturale:

API pubbliche — quello che chiamano client esterni o altri servizi. Le più costose. Cambiarle è un breaking change, e i breaking change richiedono versioning, percorsi di migrazione e comunicazione.

Confini di modulo — quello che si chiamano i tuoi servizi o pacchetti interni. Costoso. Cambiarli rompe altre parti del tuo stesso sistema.

Firme di funzione interne — quello che il tuo codice all'interno di un modulo chiama. Economico. Fai refactoring liberamente.

Dettagli di implementazione — variabili, algoritmi, strutture dati. Gratis. A nessuno fuori dalla funzione interessa.

L'errore che vedo più spesso è trattare questi livelli come equivalenti — over-engineering i dettagli interni come se fossero API pubbliche, o rompere casualmente i confini di modulo come se fossero dettagli di implementazione.

Quando l'interfaccia ti dice qualcosa

C'è una sensazione specifica quando una firma di tipo diventa complicata. I parametri si moltiplicano. Il tipo di ritorno diventa un'unione di cinque cose. Hai bisogno di un options object perché la lista degli argomenti è ingestibile.

È l'interfaccia che ti sta dicendo qualcosa — allo stesso modo in cui il codice non testabile ti sta dicendo qualcosa. Un'interfaccia complicata di solito significa che la funzione sta facendo troppe cose, o che c'è un'astrazione sbagliata al confine.

La risposta giusta non è andare avanti. È fermarsi e chiedersi come dovrebbe essere l'interfaccia — poi lavorare a ritroso verso l'implementazione che la soddisfa.

TypeScript come documentazione vivente

Quello che apprezzo di più delle interfacce tipizzate non è la prevenzione dei bug. È la comunicazione. Quando torno a un modulo che non tocco da sei mesi, i tipi mi dicono cosa si aspetta e cosa promette. Non possono essere sbagliati come può esserlo un commento, perché i tipi sbagliati non compilano.

Questo conta soprattutto quando sei l'unico sviluppatore. Non c'è nessuno a cui chiedere. L'interfaccia è la documentazione.

Cambia con cura

Tratta le interfacce come contratti, non come suggerimenti. Cambia le implementazioni liberamente — è a questo che servono. Cambia le interfacce con cura, e quando lo fai, trattala come una decisione che vale la pena registrare. Perché chiunque dipenda da quel contratto avrà bisogno di sapere perché è cambiato.