Scrivere commenti di code review con la dettatura vocale

Un commento utile durante una code review non si limita a indicare ciò che sembra sbagliato. Descrive il comportamento, spiega perché conta e rende chiaro il passo successivo. Digitare queste spiegazioni più volte può interrompere il filo della revisione. Una nota come «gestire il caso vuoto», però, rischia di lasciare troppe domande aperte.

La dettatura vocale permette di preparare la spiegazione mentre il ragionamento è ancora fresco. Sul Mac, tieni visibili le differenze del codice, apri una bozza di commento e descrivi il problema come se ne stessi parlando con una persona del team. Poi rivedi il testo prima di pubblicarlo. La dettatura raccoglie la tua spiegazione: non verifica il codice e non stabilisce se una modifica sia corretta.

1. Raccogli gli elementi prima di parlare

Dedica ogni commento a un solo problema. Individua la riga o la funzione interessata, l'input o la situazione e il comportamento osservato o atteso. Se non hai eseguito il codice, specifica che il dubbio nasce dalla lettura. Un possibile difetto non deve essere presentato come un bug già riprodotto.

Decidi anche quale risposta ti serve:

• Modifica necessaria: spiega il problema concreto o il requisito concordato da risolvere prima dell'approvazione.
• Suggerimento: chiarisci che il miglioramento è facoltativo.
• Domanda: chiedi maggiori informazioni quando non sai ancora se occorra una modifica.

Segui le convenzioni del team. Una preferenza personale non diventa un motivo per bloccare l'approvazione solo perché è espressa in modo deciso.

2. Detta il ragionamento e aggiungi dopo i riferimenti esatti

Dividi la spiegazione in tre parti: «In questa situazione ho notato questo comportamento. È importante perché produce questo effetto. Possiamo fare o verificare questa modifica?». Fai una pausa tra le idee e mantieni ogni commento concentrato su un unico punto.

Dopo la dettatura, inserisci identificatori, percorsi dei file e frammenti di codice direttamente dalla fonte. Non affidarti soltanto al riconoscimento vocale quando un simbolo può cambiare il significato del codice. Elimina le ripetizioni e i giudizi sulla persona: descrivi l'implementazione e i suoi effetti.

3. Trasforma una nota vaga in un'indicazione concreta

L'esempio seguente è inventato e presuppone che chi svolge la revisione abbia riprodotto il comportamento in locale.

Nota iniziale: «Va sistemata la ricerca vuota».

Commento rivisto:

Modifica necessaria — ricerca vuota: quando invio una ricerca contenente soltanto spazi, il pannello dei risultati resta nello stato di caricamento. Ho riprodotto il comportamento in locale con la modifica attuale. L'utente non riceve né risultati né indicazioni su cosa fare dopo.

Possiamo gestire gli input composti solo da spazi prima di avviare la ricerca e mostrare il messaggio concordato per un input vuoto? Aggiungi anche un test di questo percorso, così possiamo verificare che lo stato di caricamento termini correttamente.

Se sospetti soltanto il problema, inizia con «Leggendo questo ramo, sembra che…» e chiedi se un altro percorso gestisca già il caso. Se il messaggio non è stato concordato, chiarisci prima il comportamento atteso, senza inventare un requisito.

4. Riutilizza un modello breve

Tipo: [Modifica necessaria / suggerimento / domanda].

Contesto: in [posizione o situazione], [comportamento osservato oppure dubbio indicato esplicitamente come tale].

Effetto: questo conta perché [conseguenza specifica].

Passo successivo: possiamo [modifica mirata, verifica o spiegazione]?

Elementi disponibili: [Passaggi per riprodurre il problema, requisito pertinente o risultato di un test, se presenti].

Questi campi aiutano a organizzare la bozza, ma non sono titoli obbligatori per ogni commento. Per un piccolo suggerimento possono bastare due frasi. Se il problema riguarda più file, inseriscilo nel riepilogo della revisione con i link ai punti interessati, anziché ripeterlo sotto ogni riga.

5. Rileggi prima di pubblicare

Confronta nomi, negazioni e termini tecnici con le differenze del codice. Controlla che un «fa» non sia diventato «non fa» e che i risultati dei test citati esistano davvero. Infine, leggi il commento dal punto di vista di chi lo riceverà: è chiaro cosa rispondere o modificare senza dover indovinare la tua intenzione?

Per attività collegate, consulta le guide alle descrizioni delle pull request e alle segnalazioni di bug chiare.

TypeFree è un modo semplice per trasformare la voce in testo modificabile e scrivere più velocemente. Detta il ragionamento del tuo prossimo commento di code review, verifica i dettagli e pubblica un riscontro che aiuti a compiere il passo successivo.