Tra un anno qualcuno aprirà il progetto e si chiederà perché c'è una coda di messaggi dove sarebbe bastata una chiamata diretta. Se nessuno ha scritto il motivo, la scelta sarà ripetuta, annullata o, peggio, difesa senza sapere perché. Documentare non significa scrivere molto: significa registrare ciò che il codice da solo non dice.
Che cosa il codice non dice
Il codice dice che cosa fa il sistema. Non dice perché si è scelta una strada invece di un'altra, quali vincoli c'erano, quale alternativa è stata scartata e perché. Questo è il contenuto che si perde per primo quando le persone cambiano.
Le decisioni architetturali (ADR)
Un ADR (Architecture Decision Record) è una nota breve, una per decisione, che contiene:
- Contesto: il problema e i vincoli del momento.
- Decisione: che cosa si è scelto.
- Alternative considerate: e perché non sono state scelte.
- Conseguenze: che cosa diventa più facile, che cosa più difficile, quali rischi si accettano.
- Stato: proposta, accettata, sostituita da un'altra decisione.
Si scrive nel momento in cui si decide, quando il ragionamento è fresco. Non si riscrivono: una decisione cambiata si registra con una nuova nota che sostituisce la precedente, così resta la storia.
Si scrive un ADR quando la scelta è difficile da annullare, coinvolge più parti del sistema, o quando qualcuno, in futuro, si chiederà ragionevolmente "ma perché?".
Documentazione di API e funzionalità
Per chi usa un'interfaccia contano: a che cosa serve, un esempio funzionante, i parametri con i loro vincoli, gli errori possibili e che cosa fare. La documentazione che si può eseguire (esempi provati) invecchia meglio di quella solo descrittiva. Quando si modifica una API pubblica, si aggiorna la documentazione nella stessa modifica.
Commenti nel codice
Un commento che ripete il codice è rumore. Un commento utile spiega il perché di un'anomalia: "qui si arrotonda per difetto perché il fornitore tronca". Si segnano anche i vincoli non ovvi e i casi che il codice protegge. Quando il codice cambia, il commento cambia con lui, o si cancella.
Per chi leggerà: persone e agenti
La documentazione serve anche agli agenti che lavoreranno sul progetto: un file di regole, decisioni scritte e un indice per area li rendono più affidabili, per lo stesso motivo per cui aiutano un nuovo collega.
Dove tenere la documentazione
Vicino al codice, nello stesso repository, rivista nelle stesse modifiche. Documentazione in un altro posto, aggiornata a parte, si sfalsa quasi subito.
Segnali d'allarme
- Decisioni importanti conservate solo nella memoria di qualcuno.
- Commenti che descrivono ciò che il codice fa invece del perché.
- Documentazione che non è cambiata mentre cambiava l'API.
- ADR riscritti invece di sostituiti.
- Nessuna traccia delle alternative scartate.
Un esempio
Un team sceglie di non usare un database relazionale per un modulo. Nota scritta il giorno stesso: contesto (molti dati semistrutturati, scritture frequenti), decisione, alternative considerate (il database relazionale già in uso, scartato per il costo delle migrazioni di schema), conseguenze (le interrogazioni trasversali sono più difficili). Due anni dopo, un nuovo collega capisce la scelta in due minuti e sa quando valga la pena rivederla.
Quando usarlo
Quando si prendono decisioni architetturali, si cambiano API pubbliche, si rilascia una funzionalità o quando serve registrare un contesto che i futuri sviluppatori e agenti dovranno conoscere.
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.
documentation-and-adrsMetodo per registrare il perché delle scelte tecniche: ADR (contesto, decisione, alternative, conseguenze, stato), documentazione di API e funzionalità con esempi, commenti che spiegano il motivo. Usarla quando si prende una decisione architetturale, si cambia una API pubblica o si rilascia una funzionalità.