Conservare le tue decisioni12 / 20
Vedere la copertura del tuo intento
In questa pagina
Su quanta parte di questo software hai davvero il controllo? La copertura dell’intento risponde con un’immagine: un quadratino per ogni file di codice, disposto per modulo, e più il quadratino è scuro, più righe sono citate dalle tue spiegazioni. Ciò che è ancora vuoto e le spiegazioni non più aggiornate si vedono a colpo d’occhio. Punta un intento e i file che copre si illuminano.
Apri la copertura dell’intento
Avvia una nuova chat: prima di inviare il primo messaggio, l’area della chat mostra la scheda Intent coverage. Puoi anche aprire Settings → Intent coverage (nel gruppo del progetto corrente), dove la scheda riempie la pagina, il che aiuta con i progetti grandi.
La copertura dell’intento richiede che la cartella Implementation sia un repository Git. Finché il progetto non ha un risultato di copertura, la scheda dice “Not computed yet” e offre due modi per cominciare: “Explain” fa scrivere prima le spiegazioni all’Agent, e “Compute now” calcola la copertura dalle spiegazioni che hai già. Con repository grandi bisogna leggere ogni file, quindi può volerci un po’.
Dopo di che, la scheda si aggiorna ogni volta che Explain finisce. A destra della riga del titolo compaiono il momento in cui è terminato l’ultimo Explain e il commit di allora, con un pulsante per calcolare di nuovo.
Leggi la scheda
In cima alla scheda c’è un numero grande: la quota di tutte le righe di codice nell’ambito che le spiegazioni citano. Accanto, “3 / 6 files” indica quanti file hanno un intento alle spalle sul totale.
La barra sotto ha tre parti, con una legenda sotto:
- Referenced lines: la parte piena, lunga quanto la percentuale.
- Explanation outdated: la parte tratteggiata, file modificati dopo che le loro spiegazioni sono state scritte.
- No intent: la parte vuota, file che nessuna spiegazione cita.
Per modulo
L’area “Modules” mostra per impostazione predefinita dei punti: un punto per file, una riga per cartella. I file con un intento alle spalle diventano più scuri quante più righe sono citate; i file le cui spiegazioni sono obsolete sono tratteggiati; i file senza intento sono vuoti. Punta un punto per vedere il nome del file e quanta parte ne è citata.
L’interruttore in alto a destra trasforma i punti in barre: una riga per modulo, lunga quanto il suo numero di righe, divisa nei tre stati.
Clicca un modulo per scendere di un livello; nella riga del titolo compaiono un pulsante indietro e il percorso. Nel servizio di abbonamenti, per esempio, le righe di billing, jobs, notify e web stanno affiancate, e la riga di notify è quasi vuota: le regole per le email di notifica non sono ancora state scritte nell’intento.
Per intento
Sotto i moduli c’è l’elenco degli intenti, una riga per documento di intento, rientrata come l’albero dei documenti, con una breve riga che mostra a quanti file corrisponde. Un documento senza ancora codice alle spalle è in grigio con una riga vuota.
- Punta un documento: le righe nell’area dei moduli che non c’entrano si attenuano, e la disposizione resta ferma.
- Clicca un documento: le righe non correlate si richiudono, la barra e i punti mostrano solo il codice a cui corrisponde questo intento, e sotto il titolo dei moduli compare un chip con il nome del documento e una ×.
- Cliccalo di nuovo, clicca la × del chip o premi
Escper toglierlo.
Clicca Rinnovo, per esempio, e restano solo billing/grace.ts, jobs/renewal-job.ts e alcuni file di test. Vedi subito che cosa toccherà una modifica alle regole di rinnovo.
Che cosa significa il numero
La copertura misura quanto codice citano le tue spiegazioni. Non è qualità del codice, e non è copertura dei test. Ti aiuta a rispondere a due domande:
- Dove non c’è ancora intento? Un modulo vuoto è codice che conta poco, oppure regole già in esecuzione a cui non hai pensato fino in fondo. Queste ultime meritano un paragrafo di intento e un Explain.
- Dove le spiegazioni sono obsolete? Un tratteggio fitto indica modifiche recenti a cui le spiegazioni non sono ancora al passo; vedi Quando il codice cambia.
Non serve inseguire il 100%. Comincia dalle parti a cui tieni di più e lascia che siano le prime a scurirsi.
Parnas Index
Settings → Parnas Index guarda la stessa cosa dall’altro lato: quanto le modifiche al codice arrivano a toccare il tuo intento. Il nome viene dal principio di decomposizione in moduli di David Parnas: un buon modulo nasconde una decisione che è probabile che cambi. In Noea, un passaggio di intento rappresenta una decisione e un file di codice un modulo.
Il numero grande in alto indica quanti passaggi di intento vengono ricontrollati, in media, per ogni file modificato, con quanti sono stati controllati per intero e quanti di essi non sono cambiati. Più è alto, più decisioni una singola modifica si trascina dietro. La finestra temporale può essere di 7, 30 o 90 giorni.
La pagina ha due viste:
| Vista | Livelli | Colonne |
|---|---|---|
| Code → intents | Files, Definitions | Intents reached, Changes, Per change, No change |
| Intents ← code | Documents, Passages | Files cited, Code changes, Intent changes, No change |
Clicca una riga per aprirla sul posto. Una riga di file mostra quanta parte ne citano le spiegazioni, gli intenti che raggiunge di più e “View in Intent coverage”; una riga di intento mostra quanti file cita, il codice che lo raggiunge di più e un modo per aprire quel passaggio.
Sotto il livello dei file della prima vista c’è un grafico a dispersione “Coverage and reach”: in orizzontale, la quota di righe citate dalle spiegazioni; in verticale, quanti passaggi di intento raggiunge ogni modifica. I file in alto a destra sono molto citati e spesso modificati, quindi ogni modifica significa ricontrollare molto intento; potrebbe valere la pena dividerli. Una copertura più alta non è sempre meglio.
Se al progetto non è ancora collegata una cartella Implementation, entrambe le pagine ti chiedono di collegarne una prima in Settings → Project.