Apri la storia di un progetto e trovi messaggi come «fix», «modifiche», «aggiornato», «wip», «ancora fix». Sei mesi dopo devi capire perché una certa riga è stata cambiata, e la storia non ti dice nulla. Il messaggio di commit è una delle forme di documentazione più sottovalutate: costa trenta secondi scriverlo bene e può far risparmiare ore a chi lo leggerà, spesso tu stesso.
A chi serve un messaggio di commit
Il codice dice cosa fa il programma. Il diff di un commit dice cosa è cambiato. Il messaggio è l'unico posto in cui si può spiegare perché è cambiato. Questa informazione è preziosa in situazioni molto concrete:
- durante una revisione del codice, per capire l'intenzione prima di leggere le righe;
- quando usi
git blameper scoprire l'origine di una riga sospetta; - quando cerchi con
git logil commit che ha introdotto un bug; - quando prepari le note di rilascio di una nuova versione.
La struttura classica
Una convenzione molto diffusa nella comunità di Git prevede:
- una riga di oggetto breve, indicativamente entro 50 caratteri e comunque non oltre 72;
- una riga vuota;
- un corpo facoltativo, con righe di lunghezza ragionevole, che spiega il contesto.
Evita il doppio invio del modulo d'ordine
Se l'utente cliccava due volte su «Conferma» prima della risposta
del server, venivano creati due ordini identici. Il pulsante ora
viene disattivato al primo clic e riattivato in caso di errore.
Il controllo lato server resta necessario: questo cambiamento riduce
solo i casi più comuni.
La riga vuota non è un vezzo: molti strumenti trattano la prima riga come titolo e il resto come descrizione. Senza separazione, il titolo diventa un paragrafo intero.
L'oggetto all'imperativo
Un'abitudine utile è scrivere l'oggetto come un comando: «Aggiungi», «Correggi», «Rimuovi», «Rinomina». Un trucco per verificarlo è completare la frase «Se applicato, questo commit…»: «…aggiunge la validazione della data» funziona, «…ho sistemato delle cose» no. In inglese la forma imperativa è la convenzione più diffusa, anche perché è quella usata dai messaggi generati da Git stesso, come «Merge branch».
Più importante della grammatica è la specificità. Confronta:
| Messaggio debole | Messaggio utile |
|---|---|
| fix bug | Correggi l'arrotondamento dei totali sotto 1 euro |
| update | Aggiorna la libreria di parsing delle date alla 3.2 |
| modifiche al login | Blocca l'account dopo cinque tentativi falliti |
| refactoring | Estrai il calcolo delle spedizioni in un modulo dedicato |
Il corpo: spiegare il perché
Non tutti i commit hanno bisogno di un corpo. Correggere un errore di battitura in un commento non richiede spiegazioni. Ma quando la modifica nasce da una decisione non ovvia, il corpo è il posto giusto per raccontarla:
- qual era il problema e come si manifestava;
- perché hai scelto questa soluzione e non un'altra più ovvia;
- quali effetti collaterali o limiti conosci;
- riferimenti utili, come il numero della segnalazione nel sistema di tracciamento.
Evita invece di ripetere il diff a parole («cambiata la variabile x in y alla riga 40»): quello lo mostra già Git.
Commit atomici
Un buon messaggio è facile da scrivere solo se il commit ha un unico scopo. Se per descriverlo devi usare «e» tre volte, probabilmente sono tre commit. I commit atomici portano vantaggi pratici:
- Revisione più semplice: ogni modifica si legge e si valuta da sola.
- Annullamento preciso:
git revertrimuove esattamente una modifica, senza trascinare altro. - Ricerca dei bug efficace:
git bisect, che individua il commit colpevole per bisezione, funziona molto meglio con commit piccoli e coerenti.
L'area di staging aiuta molto: con git add -p puoi selezionare singoli blocchi di modifiche dallo stesso file e distribuirli in commit diversi.
Convenzioni strutturate
Alcuni team adottano formati come i Conventional Commits, in cui l'oggetto inizia con un tipo: feat:, fix:, docs:, refactor:. Il vantaggio è che strumenti automatici possono generare note di rilascio o decidere il numero della prossima versione leggendo la storia. Lo svantaggio è un po' di rigidità. Se il tuo team lo usa, rispettalo con coerenza; se lavori da solo, valuta se il beneficio giustifica la disciplina richiesta.
Quando riscrivere la storia
Durante lo sviluppo su un tuo branch locale è normale fare commit provvisori. Prima di condividerli, puoi riordinarli e riscrivere i messaggi con un rebase interattivo, così la storia pubblicata racconta il lavoro in modo pulito. La regola da non violare: non riscrivere commit già condivisi con altri su rami comuni, perché costringeresti tutti a riallineare le proprie copie.
In sintesi
- Il messaggio di commit è l'unico posto in cui spiegare perché il codice è cambiato.
- Oggetto breve e specifico, riga vuota, corpo facoltativo che racconta contesto e motivazioni.
- Scrivi l'oggetto come un comando e verifica che completi la frase «Se applicato, questo commit…».
- Un commit, uno scopo: i commit atomici semplificano revisione, revert e ricerca dei bug.
- Riordina i commit locali prima di condividerli, mai quelli già pubblicati.
