"Credo che funzioni così" è una frase che in un progetto di software si paga più tardi. Le librerie cambiano, le funzioni vengono deprecate, e il codice scritto a memoria porta con sé i pattern di tre versioni fa. Lo sviluppo guidato dalle fonti propone una regola semplice: ogni scelta che dipende da un framework si appoggia alla sua documentazione ufficiale, e lo dice.
Il processo
1. Rilevare stack e versioni. Prima di scrivere codice si leggono i file delle dipendenze del progetto (per esempio quelli che elencano pacchetti e versioni). Una regola vale per una versione: senza sapere quale, non si sa se è corretta.
2. Leggere la documentazione ufficiale. Per la funzione che serve, si consulta la documentazione del framework per la versione in uso, non un articolo di blog né una risposta su un forum. Se la versione precisa non è reperibile, lo si dichiara.
3. Seguire i pattern documentati. Si implementa come la documentazione indica, anche quando la memoria suggerisce un'altra strada. Se si decide di discostarsene, si spiega perché.
4. Citare le fonti. Ogni decisione specifica del framework porta con sé il riferimento (il link alla pagina) accanto al codice o nella descrizione della modifica. Così chi rivede può verificare in un minuto, e chi legge tra un anno sa da dove viene la scelta.
Perché serve
Gli assistenti e le persone condividono un limite: ricordano la versione che hanno visto di più, non quella che il progetto usa. L'API deprecata che compare ovunque nei tutorial è quella che si riscrive più volte. Una fonte ufficiale e datata trasforma un'opinione in un fatto controllabile.
Le scuse più comuni
| Scusa | Realtà |
|---|---|
| "Conosco bene questa libreria" | Quale versione? Le interfacce cambiano, e la memoria è di un'altra. |
| "Ci metto un secondo a cercare, ma intanto vado" | È la ricerca che costa meno di una riscrittura. |
| "Un tutorial lo dice" | Un tutorial è una fonte secondaria, spesso di un'altra versione. |
Segnali d'allarme
- Codice specifico di un framework scritto senza aver controllato la documentazione della versione in uso.
- Frasi come "credo" o "mi pare" su un'API invece di una fonte citata.
- Un pattern implementato senza sapere a quale versione si applica.
- Forum e blog citati al posto della documentazione ufficiale.
- API deprecate usate perché compaiono spesso.
- Nessuna lettura dei file di dipendenze prima di scrivere.
- Codice consegnato senza riferimenti alle fonti per le scelte legate al framework.
Un esempio
Si deve gestire il caricamento dei dati in un componente di un framework. Si legge nel file delle dipendenze che la versione è la 5; la documentazione della 5 indica un modo diverso dalla 4, ancora molto citato online. Si usa quello della 5 e nella descrizione della modifica si aggiunge il link alla pagina. Un revisore lo verifica in un minuto.
Quando usarlo
Quando si vuole codice con fonti verificabili e libero da pattern obsoleti; quando si lavora con qualunque framework o libreria in cui la correttezza conta.
Questo metodo deriva dalla famiglia di skill open source agent-skills di Addy Osmani (licenza MIT), riscritta e adattata.
Questo articolo è una skill di OIAR
Quello che hai letto è il contenuto di una skill del catalogo OIAR, scritto per le persone. Una conoscenza come questa ma più ricca e profonda, scritta per gli agenti, guida le interviste, l'analisi e il report dentro la piattaforma. Le skill si usano in OIAR: per provarla su un tuo progetto serve un account.
source-driven-developmentMetodo per basare ogni scelta di framework o libreria sulla documentazione ufficiale della versione in uso: rilevare lo stack, leggere la fonte, seguire i pattern documentati, citare i riferimenti. Usarla quando si scrive codice con framework o librerie in cui la correttezza conta o si sospettano pattern obsoleti.