Perché dovrei scrivere un messaggio di commit?

A tutte le persone che dicono "commetti solo quando hai un messaggio utile e ben pensato da scrivere, e quando la tua funzione è completa al 100% e hai dei test unitari per questo", dico: Tu " ancora nella mentalità SVN.

Se utilizzi git , questo è quello che definirei un flusso di lavoro intelligente:

1. Impegna tutte le volte che vuoi . Scrivi qui un vecchio messaggio rapido. Nessuno lo vedrà comunque.
2. Dopo aver detto, 10 commit, hai terminato la funzione su cui stavi lavorando. Ora scrivi test e commetti quei test. O qualunque altra cosa tu voglia. Se ti piace il TDD, scrivi prima i test, non mi interessa, nemmeno git.
3. git rebase -i del primo commit "disordinato" che hai aggiunto e correggi la tua cronologia locale schiacciando, modificando, omettendo e altrimenti ripulendo la cronologia recente in commit logico e pulito con messaggi carini .
4. Dopo la pulizia, chiedi a qualcuno di contattarti.
5. Risciacqua e ripeti.

Si noti che il passaggio 3 è quando si finisce con quei bei commit che si cercavano, e che usando SVN si dovrebbe astenersi dal commit fino a quando non si sono compiuti i primi due passaggi, che è ciò che la maggior parte delle altre risposte stanno suggerendo. IOW, non vuoi infliggere il tuo codice scritto a metà, non testato ad altri, quindi non impegnarti per una settimana, fino a quando la tua funzione non sarà completata. Non stai utilizzando il controllo della versione al massimo del suo potenziale.

Nota anche che, ovunque tra i passaggi 1 e 3, puoi git push le tue modifiche al tuo mirror repo privato sul server per ottenere backup gratuiti se l'HDD del laptop muore.

Perché quando un povero manutentore cerca un bug e scopre che è stato aggiunto in rev. xyz, vorrà sapere che rev. xyz doveva fare.

Commenta il tuo codice sorgente, giusto?

Scrivi i commenti migliori, quelli che dicono perché come il codice dice solo come ?

Il messaggio di commit è un tale commento, e quindi è molto importante e più si pensa a far bene, più è utile a un futuro manutentore del software.

Per ogni software attivo, questo particolare commento finirà per essere mostrato in qualcosa come

(trovatoallink ). Ciò consente di vedere chi ha funzionato sul software quando e cosa hanno fatto.

Tieni presente che questo è l'obiettivo finale per il commento di commit, ovvero la visualizzazione in tale elenco che dice " cosa " al tuo futuro sé o al tuo collega, e CHE è il motivo per cui dovresti stare attento a scrivere buoni messaggi di commit.

Se il messaggio di commit ti sembra stupido, sembra che tu stia usando commit errato.

I commit dovrebbero essere fatti per una buona ragione: dovrebbero essere correlati alle attività che hai suddiviso per la funzione su cui stai lavorando. Sia che queste attività siano formali o solo nella tua mente, ogni modifica che commetti dovrebbe più o meno completare un'attività e quindi essere funzionale in qualche modo.

Quindi i tuoi messaggi di commit hanno uno scopo molto migliore. Descrivi l'attività completata e se non è stata tracciata da qualche altra parte, perché è stata necessaria l'attività o a quale scopo serve:

• Rifattorizzato la classe utente per una migliore incapsulamento
• Stub API creati in modo che le interfacce possano essere utilizzate nella classe controller
• Conversione della classe del database in una classe astratta in modo che un database fittizio possa essere utilizzato nei casi di test

Quindi tu o altri sviluppatori potete consultare il repository o la cronologia dei file e vedere facilmente dove sono avvenute determinate evoluzioni e perché. Oppure, se una particolare revisione viene ritenuta colpevole di un bug, il messaggio di commit darà un indizio sul motivo per cui è stata inserita la riga, in modo che non lo si estenda e si possa rompere qualcosa che si pensava fosse risolto, e puoi invece correggerlo nel modo giusto.

Riduce il numero di WTF / minuto;)

che si traduce in una squadra più felice (che non ti odia) e una migliore uscita del team potenzialmente a costi inferiori

I commenti sul commit non risolvono tutto. C'è sempre la possibilità che ingannino tanto quanto aiutano - specialmente quando gli sviluppatori sono arrabbiati per doverli inserire. Prova questo: considerali come una briciola di pane nei boschi o un waypoint alpinistico o proiettili traccianti. Fatto bene, possono delineare un percorso altrimenti confuso.

Non fare un grosso problema con loro. Sii sincero:

• "Entità dell'indice spaziale modificate, Daos e UI per gestire la feature X"
• "Check-in incrementale per richiesta di funzioni # 1234 e bug # 5678"
• "Ho rotto l'ultima build: questi sono i file che ho perso."

Resta breve e "grande immagine". Se possibile, fai riferimento a un numero di problema nel tuo sistema di funzionalità / bug. Alcune interfacce utente di controllo versione includono un campo per questo genere di cose.

Quindi il resto del tuo team sa che il WTF sta eseguendo il controllo delle modifiche alla struttura del progetto.

perché se non ti eserciti ad inserire messaggi di commit decenti, finirai come il mio collega che inserisce messaggi come

no changes

o

testing

per i commit con oltre un centinaio di file modificati (non scherzo qui !!).

Se diventi uno sviluppatore del genere, sembrerai stupido agli occhi del resto del mondo, non importa quanto pensi che sia stupido inserire un messaggio.

Perché ti impegni se le modifiche non sono significative?

Impegna semplicemente le modifiche che hanno un significato. Per esempio. Ho fatto un refactoring piuttosto grande l'altra settimana che mi ha richiesto circa 3 giorni. Avrei tonnellate di commit durante quel periodo. Alcuni erano cambiamenti piuttosto piccoli ("ribattezzato classe da X a Y per riflettere la nuova responsabilità" o "spostato il metodo Z () in classe Q") e altri erano davvero grandi. Quando ho finito con una funzione / refactoring, controllo se alcuni commit potrebbero essere schiacciati (almeno git lo supporta, non so altri strumenti), ma di solito li lascio perché è utile in seguito.

Immagino che non ti impegni a modificare una riga, quindi dovrebbe avere un significato. Descrivi cosa hai fatto dall'ultimo commit.

immagina una condizione in cui hai rotto il tuo sistema apportando qualche modifica e realizzalo dopo diversi commit da parte della squadra. Non ricordi quale sia stato il cambiamento ma ricordi che qualcosa potrebbe andare storto quando stai migliorando la funzione X o rimuovendo un file dal modulo Y.

Ma sfortunatamente il numero di revisione non ti dice quando hai cambiato X o Y. Quindi la tua scelta o legge tutti i codici impegnati durante gli ultimi N giorni o legge solo i messaggi di commit dettagliati che hai scritto (molto più leggibile del codice).

Quindi se scrivi lo stesso, noioso, inutile, non correlato testo nel messaggio di commit, perché devi, è più dannoso che avere un messaggio di commit. Perché invece di trovare la radice del bug il messaggio sbagliato ti fuorvierà.

Quindi prova a scrivere messaggi di commit significativi ogni volta che esegui il commit, cosa che può aiutarti anche tu e il maintainer.

Se lavori con gli altri, allora i messaggi di commit sono molto importanti per vedere effettivamente cosa hanno fatto gli altri: cercare le differenze per ognuno di essi è molto più lavoro e potresti non riuscire a capire perché qualcuno lo ha fatto. Se lavori con gli altri e qualcuno (forse non tu) deve guardare indietro, per esempio per tenere traccia di come il comportamento è cambiato dalla versione precedente in modi inaspettati ... stai davvero rendendo la vita difficile non usando un suggerimento utile nel commit Messaggio.

Se lavori da solo ... su un progetto che è per lo più codificato "così com'è" (ad esempio un singolo sito Web o script semplice) posso più o meno vedere da dove vieni. Se lavoro su qualcosa del genere, mi interessa solo la data / ora o le modifiche più recenti quando si continua a lavorare su qualcosa (hai un punto da ripristinare, ma ciò conta solo durante lo sviluppo, non dopo averlo implementato). Il controllo della versione è solo un modo per fare copie di backup con pochi punti a favore - Sono pienamente d'accordo che non sta facendo un uso completo del sistema - ma su alcuni progetti su piccola scala, che potrebbero non essere necessari.

Mi è venuto in mente il pensiero prima che Version Control venga usato in due modi divisi, uno di documentare i cambiamenti nel progetto e altri come una mano per gli sviluppatori sul posto ... e questi due sono totalmente diversi da ognuno altro. I messaggi di commit sono molto importanti in un modo e potrebbero essere per lo più inutili nell'altro.

Ti manca qualcosa. Lì deve essere un motivo per eseguire un commit altrimenti non lo faresti.

Tutto ciò che devi fare nel commento è mettere il motivo in parole, anche se è solo wip: adding new state objects

Come molti altri, faccio un po 'di programmazione nel mio tempo libero e uso un sistema di controllo di revisione per tracciare sia il mio sviluppo che i cambiamenti. La quantità di tempo libero che ho a disposizione varia notevolmente da una settimana all'altra e da un mese all'altro. Molte sono state le occasioni in cui non avrei avuto il tempo di codificare un progetto per settimane o addirittura mesi, e in genere avrei trascorso da 10 minuti (tipico giorno) a 40 minuti (buon giorno). Quelle di certo non sono ottime condizioni - specialmente per i problemi di debug.

Era essenziale tenere appunti che non si sarebbero persi e che erano facilmente recuperabili. Alla fine di ogni sessione, il lavoro della sessione verrà eseguito con un messaggio dettagliato. Potrei quindi passare attraverso la cronologia dei commit e seguire i miei progressi e la mia riflessione. Questo mi ha permesso di riprendere dove ero la settimana scorsa, o il mese scorso con il minor dispendio di tempo prezioso.

Il punto che sto cercando di illustrare è che i buoni messaggi di commit aiutano te (e chiunque altro ti insegue) a capire cosa è successo, cosa sta succedendo, dove vanno le cose e soprattutto perché.

Pensaci logicamente per un minuto. Quando stai commettendo ciò significa che qualcosa è stato fatto. Se non lasci alcun messaggio, come faranno le altre persone a sapere cosa è stato fatto?

Se non commentate i vostri commit, potreste essere tentati di commentare il cambiamento nella fonte. Col tempo, questo può ingombrare la fonte.

I messaggi di commit sono un modo rapido per sapere cosa sta andando in quel check-in e aiuteranno gli altri sviluppatori del tuo team quando vogliono sapere quale aspetto del codice è cambiato in quali revisioni (per può motivi).

Su una nota correlata, suggerirei di specificare il numero del bug tracker (spero che ne stiate usando uno) nel messaggio di commit, in modo che sia utile per il futuro tracciare facilmente le cose.

In modo che il manutentore di quel codice 1 anno dopo sappia a chi dare la caccia per quel codice atroce. :)