Le regole per i messaggi di commit

Se vi è mai capitato di gestire un progetto con git allora sicuramente vi è anche capitato di scrivere decine, centinaia o migliaia di messaggi di commit. Se siete come me, sicuramente la maggior parte di questi messaggi sono di poca sostanza se non completamente privi di significato.

Meaningful messages

In teoria, i messaggi di commit sono indispensabili per comunicare i cambiamenti avvenuti nel codice dal commit in questione. Se scritti bene, allora sono sicuramente utilissimi anche in pratica. Questo diventa ancor più importante se nel progetto ci lavorano diverse persone, specialmente se il codice passerà sotto gli occhi di un collega che dovrà fare la revisione. Durante la revisione, la lista dei commit con i messaggi allegati a ciascuno di essi dovrebbe essere il punto di partenza per capire velocemente che cosa (e perché) cambia nel codice.

Spero che a questo punto ognuno che sta leggendo sia almeno un po' convinto che i messaggi di commit hanno un suo perché. Purtroppo, non tutti (me compreso) sono bravissimi a scrivere messaggi chiari e utili. Fortunatamente, ci sono delle “regole” che facilitano tutto il processo.

Alcune di queste regole sono prese direttamente dal manuale di git oppure da come git funziona di per sé.

1. Limita l'oggetto del messaggio a 50 caratteri

Dal manuale di git:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change

Anche se non esplicitamente richiesto o imposto, è consigliabile tenere l'oggetto (o il messaggio se è corto) lungo al massimo 50 caratteri. Questo perché l'oggetto deve descrivere in modo conciso il cambiamento senza entrare nei dettagli. Questo limite aiuta a non entrare troppo nei dettagli.

2. Scrivi il primo carattere dell'oggetto in maiuscolo

Per questo non serve una spiegazione.

Scrivere:

Fixed typo in error message

invece di

fixed typo in error message

3. Non mettere un punto alla fine dell'oggetto

Non serve. Poi con un limite di 50 caratteri lo spazio è prezioso.

4. Usa l'imperativo nell'oggetto

Questo praticamente ti viene imposto da git nei messaggi automatici. Per esempio:

Merge branch “bug-fix” Revert “Create new class”

5. Separa il corpo del messaggio dall'oggetto con una riga vuota

Ovviamente, se i 50 caratteri non bastano, allora puoi semplicemente aggiungere un corpo al messaggio. Per separare l'oggetto dal corpo basta usare una riga vuota. Questa regola è definita nel manuale di git:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

Per dare un esempio:

Fix blank lines issue

In #254, probably because the tag is followed by , cstta sets regtype 'V'(linewise) though its keeper doesn't end with . And setreg() adds extra at @“. Remove this extra and fix adding method.

6. Il corpo del messaggio deve spiegare il “cosa” e il “perché”, non il “come”

Il codice dovrebbe essere sufficientemente chiaro in quello che fa, quindi aggiungere dettagli di come il codice funziona è superfluo ed una perdita di tempo. Quello che importa per chi legge il messaggio è:

  1. Cosa è stato cambiato
  2. Come funzionava il programma prima e come funziona adesso
  3. Perché è servito questo cambiamento