Come convincere i miei colleghi sviluppatori a WANT di aggiungere commenti ai commit del codice sorgente?

So che Subversion (quello che stiamo usando al lavoro) può essere configurato per richiedere commenti sugli commit, tuttavia non sono in grado di accenderlo semplicemente. So che la mia ragione per commentare i miei commit è perché è utile, se non altro come un jogger di memoria, capire rapidamente il motivo dietro il commit. Tuttavia, questo non sembra essere abbastanza per combattere le due risposte che ottengo sempre:

1. Ci vuole troppo tempo e voglio solo inserire le mie modifiche nel repository.
2. È abbastanza facile solo guardare le differenze.

Mostro anche loro il valore di inserire semplicemente un ID di emissione JIRA e come viene automaticamente legato al problema, ma ancora nessun dado con loro.

Peggio ancora, la persona che può effettuare la chiamata si trova nello stesso campo: non vuole preoccuparsi e sta bene guardando i diff.

So che è la cosa giusta da fare, ma come posso far loro vedere la luce? Anche se non riesco a convincere i miei colleghi sviluppatori, come posso convincere il management che è la cosa giusta da fare per l'azienda?

Focus su "Perché". È tutto molto bello guardare le differenze e vedere che qualcuno ha cambiato il flusso logico di una sezione di codice o qualcosa del genere, ma perché l'hanno cambiato? Il motivo è di solito nel biglietto associato (JIRA per te).

Potrebbero chiedersi perché il "Perché" sia importante, ma in 2 anni quando hai riscontrato un bug che è un effetto a catena di quel cambiamento, sapere perché è stato fatto è incredibilmente importante non solo per correggere il tuo nuovo bug, ma anche assicurarti non fai riemergere il vecchio bug.

C'è anche il motivo dell'auditing. Commit vincolanti e ID ticket rendono davvero facile dire ok, stiamo eliminando la versione 2, questo risolve i difetti 23, 25, 26 e 27 ma non ci sono commit contro il difetto 24, quindi è ancora eccezionale.

Fagli fare le fusioni e gestire l'assistenza. Ancora una volta forse non sei in grado di farlo, ma se ti ritrovi a risolvere un problema di un precedente impegno, invialo educatamente oltre il recinto e dì. Non posso dire cosa hai fatto perché non ci sono commenti di commit, hai apportato queste modifiche che devi capire.

Anche per la fusione di filiali. Non sono sicuro che ti ricada o no, ma questa è un'area che ho trovato utili i commenti.

Ancora una volta, non nella tua barca, ma quando gestivo un team di software ho detto loro che, se avessero fatto commenti di commit, li avrei usati in un rapporto settimanale sullo stato. Ho ottenuto ottimi impegni dopo quello ed è stato più facile per me tenere traccia di quello che stava succedendo anche come manager.

Abbiamo bisogno dei commenti per il check-in per lo stesso motivo per cui abbiamo bisogno di interruzioni di riga e spaziatura nel nostro codice. Per rendere le cose più facili da rintracciare, capire leggere e comprendere.

A volte è necessario un confronto diff, ma spesso no. Costringere gli sviluppatori a confrontare le differenze quando tutto ciò di cui avevano bisogno era leggere 2-3 frasi è una totale perdita di tempo. Mi chiedo perché non vedono il valore del tempo degli sviluppatori.

• Dai il buon esempio. Trasforma i tuoi messaggi di commit in un brillante esempio di utilità. Includi riferimenti a qualsiasi altro sistema utilizzato dal tuo team per gestire storie e difetti. Inserisci una breve dichiarazione che riassuma il cambiamento e una buona spiegazione del perché il cambiamento è necessario e non qualcos'altro in ogni invio.
• Ogni volta che la mancanza di un messaggio di commit decente ti fa lavorare di più, fai una domanda al mittente. Sii persistente con questo (ma non un coglione).
• Se non supera il tuo ruolo, scrivi uno script che invii un log delle modifiche giornaliero usando i messaggi di commit. Ciò conferirà credibilità alla tua argomentazione secondo cui messaggi utili hanno un vantaggio oltre alla navigazione attraverso le revisioni. Questo potrebbe anche aiutare a ottenere la gestione dalla tua parte, poiché vedranno giorno per giorno cosa sta succedendo.
• Identifica i tuoi alleati. Spero che ci sia almeno un'altra persona che sia d'accordo con te (forse silenziosamente non dissentendo). Trova quella persona o quelle persone e convincile ulteriormente in modo da non essere solo.
• Quando si presenta l'opportunità di menzionare il modo in cui i messaggi di commit decenti ti hanno fatto risparmiare tempo (o i messaggi scadenti ti sono costati tempo), approfittane.

Non aver paura di essere la ruota cigolante. Combattere le cattive abitudini degli altri è spesso una guerra di logoramento.

Questa deve essere una delle domande più bizzarre che ho sentito. Le persone trascorrono ore o addirittura giorni a riparare qualcosa e altri 2 secondi in più per digitare un messaggio di commit è troppo lungo ?! Devo dire che mi preoccuperei di lavorare con persone così miopi. Ovviamente non stanno usando i loro strumenti per avvicinarsi al loro pieno potenziale.

Ecco un esempio di una revisione del codice in cui sono stato coinvolto la scorsa settimana. Il nostro software di controllo della versione non conserva la cronologia tra le fusioni, quindi per le modifiche precedenti devi trovare il ramo esatto in cui è stata effettuata, altrimenti il ​​messaggio di commit mostra solo qualcosa come "unito dal ramo Y". Il ramo Y potrebbe mostrare "unito dal ramo Z" e un ramo a pochi livelli di nidificazione più profonda ha effettivamente il messaggio di commit reale.

Un nuovo dipendente non sapeva come rintracciare correttamente la cronologia, il che significa che stava essenzialmente lavorando solo con i diff. Vide alcuni commenti commentati relativi al bug che stava rintracciando. Quando ha decommentato il codice, il suo bug è scomparso. Presumeva che qualcuno avesse commentato il codice durante il debug e lo avesse erroneamente verificato.

Questo non è stato giusto per un paio di noi durante la revisione del codice, quindi ho rintracciato il vero messaggio di commit e ho scoperto che c'era un motivo valido per rimuovere quel codice un anno fa. Il nuovo dipendente è stato in grado di correggere il suo codice per correggere il bug appena scoperto senza reintrodurre quello precedente.

Esistono modi migliori per evitare di introdurre questo tipo di regressioni, come i test unitari approfonditi, ma in qualche modo non vedo le persone che non riescono a preoccuparsi di un messaggio di commit di 2 secondi "perdere tempo" nel test unitario.

Ho avuto esattamente lo stesso problema qui, quindi ho aggiunto un hook di pre-commit a Subversion in modo che non accettasse alcun commit che non iniziava con il numero User Story (alcune corrispondenze di pattern di base per un formato previsto).

Non c'è nulla che gli impedisca di entrare in 000-0000, ma una volta solo un idiota dirompente inventerà un numero quando avranno un numero perfettamente accettabile lì.

L'ho fatto dopo aver trascorso giorni a cercare di scoprire in quale build sono state raccolte le storie degli utenti. Sì, è stato per affrontare un errore di processo altrove, ma è ancora incredibilmente preziosa informazione da tracciare.

I buoni commenti di commit sono come una buona documentazione, una cache per il tuo cervello lento e defunto o una cache del risultato di lunghi debug / analisi dei problemi / indagini.

Ad esempio ogni volta che passi il tempo a capire qualcosa, come il debug, l'analisi dei registri o altro, i tuoi risultati e risultati sono preziosi. Naturalmente la maggior parte delle attività può essere ripetuta, ma potrebbe richiedere del tempo. Quindi dovresti sempre documentare i tuoi risultati.

Tuttavia, la documentazione richiede tempo e talvolta non è necessaria, come "abbiamo dovuto farlo una volta sola, quindi perché scriverla". Va bene, ma non appena fai la stessa cosa una seconda volta perché non hai documentato i risultati la prima volta, allora è ovviamente intelligente documentare i risultati.

Quindi se i tuoi colleghi ritengono che sia troppo lavoro aggiungere commenti di commit, ad esempio almeno indicare il caso / Ticket Jira che stavano risolvendo, beh, allora potrebbero essere motivati ​​dalla pressione di rispondere costantemente alle domande sul motivo di ogni di modifiche.

A mio avviso, la documentazione dovrebbe essere prodotta in funzione delle informazioni richieste. Ad esempio, la corrispondenza postale è un sistema di documentazione piuttosto valido. Le domande ricevono risposte che possono essere successivamente recuperate, ecco come le mailing list e i forum funzionano in pratica come basi di conoscenza.

Sfortunatamente, dove lavoro, la posta viene eliminata automaticamente dopo 3 mesi, quindi non sempre funziona in pratica.

Cerca il perdono, non il permesso.

Mentre duro, ho fatto proprio questo. Avevo una divisione del 50/50 tra le persone che sostenevano e le persone che si opponevano, la maggior parte delle quali erano allo stesso livello di me nel gruppo. Gli argomenti erano "Non posso essere disturbato" e "Qual è il punto?". (Entrambi indicano apatia e pigrizia, non preoccupazioni autentiche).

Ho aggiunto un hook pre-commit che ha semplicemente misurato la lunghezza della stringa e ha dato un messaggio leggermente divertente prima di rifiutarlo. Ho inserito il mio nome nel messaggio, quindi la responsabilità di "questo oltraggio" era chiara. Naturalmente, "l'opposizione" potrebbe facilmente rimuoverlo, ma scavare negli script richiederebbe più sforzo che aggiungere un altro commento!

Per una settimana ho ricevuto messaggi come * * (eliminazione esplicativa) o kjhfkwhkfjhw. Successivamente, hanno iniziato a comparire i messaggi di base.

Un anno dopo e gli scettici usano commenti significativi e ammettono davvero quanto fossero miopi. Non avrei mai potuto ottenere il consenso, ma di certo ho ricevuto perdono e forse credibilità. Funziona, la gente lo usa.

Se vuoi essere più congeniale (o sentire che potresti finire nei guai), chiedi l'autorizzazione per aggiungere un hook di commit per un periodo di prova. Dì che se alla gente non piace in 2 o 4 settimane, lo eliminerai. È probabile che perderanno interesse ... o cresceranno per piacere.

Di solito convinco le persone attraverso:

• dialettica con buoni motivi di supporto
• conducendo per esempio
• logoramento

Se volessi che il nostro team facesse qualcosa di abbastanza grave, continuerei a infastidire fino a quando non avrò la mia strada. Cerco di infastidire in quei momenti in cui posso sottolineare che avremmo potuto risparmiare tempo / denaro se avessimo già fatto X.

Ulteriori buoni motivi per inviare commenti:

• Generazione di ChangeLog automaticamente dai commenti.
• Audit trail per correzioni di errori, aggiunte di funzionalità. Questo è utile sia all'interno che all'esterno della squadra.
• Rendi più utile la posta di commit.
• Impedimi di chiedere allo sviluppatore cosa fa il commit X (dopo quasi ogni commit).

• Controlla i tuoi log SVN per qualcosa di oscuro fatto 6 mesi fa.
• Poni alcune domande su questa cosa senza dire quando è stato fatto
• ???
• Profitto

Come fai venire loro voglia di aggiungere buoni commenti?

Da un'esperienza con un collega che ho appena avuto. Alla fine di un progetto abbiamo dovuto scrivere un documento di sintesi di tutte le modifiche apportate durante il progetto. Non avendo fatto buone note sul commit, il mio collega ha trovato questo compito piuttosto dispendioso in termini di tempo e ora è passato a fare commenti piuttosto lunghi con ogni commit.

Quindi, da asporto, una soluzione potrebbe essere quella di consentire agli sviluppatori di scrivere documenti di riepilogo alla fine del progetto che descrivano in dettaglio quali modifiche sono state apportate a quali file, quali file sono stati aggiunti / rimossi e perché.

Proporre questo alla gestione a porte chiuse:

Si verifica lo scenario peggiore: tutti gli sviluppatori di livello senior escono dalla porta.

Mentre la società si arrampica per riempire i posti vuoti degli sviluppatori, il team di gestione ha il compito di comunicare lo stato del sistema al cliente.

Chiedi loro cosa pensano che faciliterebbe il loro lavoro nel ricostruire la storia dell'app:

Leggendo un semplice inglese si impegna a descrivere chiaramente lo stato mutevole del sistema?

O preferirebbero guardare alle differenze di codice e capirlo da soli?

Immagino che un modo per convincerli sarebbe effettivamente provare il dolore che stai provando.

Ad esempio, supponiamo che stiano lavorando al seguente problema: hanno un bug che, in qualche modo, è apparso quando è stata implementata un'altra correzione di bug per lo stesso codice (oh l'ironia). Poter cercare questo dalla semplice ricerca dei messaggi di commit sarebbe fantastico (e quindi scoprire chi l'ha scritto).

Un altro modo sarebbe spiegare loro che il messaggio di commit potrebbe essere utile per dare un suggerimento sul perché qualcosa è stato implementato in un certo modo. Anche se il messaggio di commit dice semplicemente "caratteristica X", puoi ancora avere un'idea di chi lo abbia implementato, quindi sai con chi parlare.

Tuttavia, questo non sembra essere abbastanza per combattere le due risposte che ottengo sempre:

1. Ci vuole troppo tempo e voglio solo inserire le mie modifiche nel repository.
2. È abbastanza facile solo guardare le differenze.

Hai provato a lanciare una sfida ai tuoi colleghi sviluppatori in modo che possano trarre qualche altro vantaggio dal mettere commenti? Si potrebbe vedere questo da una delle due diverse angolazioni:

1. Potenziare il loro gioco - Questa può essere la prospettiva più complicata da prendere, ma l'idea qui sarebbe che lo facciano per un certo periodo di tempo e si abituino all'idea in modo che l'abitudine sia di impiegare più tempo per andare dall'altra parte. Un altro punto qui è la quantità di controllo che avrebbero i commenti? Se vuoi un racconto nel commento, potrei capire il loro punto.
2. Sovvenzioni a una modifica: è qui che avresti una sorta di concorso come un modo per ottenere il buy-in iniziale per provare questo o offrire qualche altro tipo di incentivo per fare in modo che la modifica venga effettuata per un po '.

Qualcos'altro da considerare è quanto sai cosa gestiscono i tuoi colleghi sviluppatori dove lavori? Se ieri stanno provando a fare 10 cose, allora potrei capire che potrebbero non voler cambiare ciò che vedono come qualcosa che già funziona. Stai cercando di dire loro: "No, questo non funziona?" Se è così, allora posso vedere come possono essere un po 'difensivi o combattivi su questo. Se stai cercando di dire loro, "Mentre questo potrebbe funzionare, esiste un'alternativa che potrebbe essere migliore ...", allora potresti avere una possibilità. Avere un atteggiamento "più santo di te" qui non ti aiuterà, IMO.

Un altro modo di vedere questo è come un modo per gli sviluppatori coinvolti di far crescere la loro carriera: dovrebbero possedere la documentazione del loro lavoro.

Oltre ad altri punti sollevati nell'articolo sopra citato, c'è la possibilità di essere in grado di rivedere le modifiche al codice per scoprire dove / quando / perché è stata effettuata una modifica. Ciò potrebbe essere vitale per rintracciare un bug inafferrabile.

Dopo averli convinti dell'importanza di commentare i tuoi commit, puoi creare uno script che forza i commenti sui commit, altrimenti fallirà. Puoi anche specificare un minimo di caratteri per assicurarti che sia un commento significativo. Questo li aiuterà a "ricordare".

Tuttavia, è importante che capiscano il perché come ha detto @Kevin, altrimenti aggiungeranno semplicemente un commento casuale.

Hai recensioni di codice? Una cosa che può aiutare è stabilire una regola secondo la quale qualsiasi commit o fusione deve essere esaminato e approvato da un altro sviluppatore. Quindi, se sei il revisore, dovresti chiedere allo sviluppatore che effettua il commit di spiegarti cosa ha fatto. Una volta fatto, dovresti chiedergli di scrivere nel commento ciò che ti ha appena detto. Spesso quando non si può spiegare coerentemente le modifiche apportate, significa che tali modifiche non avrebbero dovuto essere apportate in primo luogo.

Devo dire però, come possono le persone opporsi a qualcosa di ovviamente utile come inviare commenti? Non ci vuole molto, ed è un tempo ben speso. Scrivere un commento ti costringe a pensare a quello che hai appena fatto. Potrebbe anche farti guardare le differenze per assicurarti di aver effettivamente fatto ciò che pensi di aver fatto e che non hai fatto nulla di stupido.

Quando non scrivi i commenti, sei sciatto e indisciplinato. E se insisti che non dovresti essere obbligato a scrivere i commenti, allora sei intenzionalmente negligente.

Digli che è l'unico modo per avere la possibilità di mantenere il tuo pasticcio procedurale di 50.000 metodi di linea, quindi considera di scrivere un codice migliore e più esplicito in futuro in modo da non dover affrontare un mucchio di commenti inutili che gonfiano la tua base di codice.

Questo è un elemento di modifica del processo: chiedi a un manager di assegnare il codice sviluppato da "x" a "Y" per i controlli di qualità sul solo codice, incluso il QA dei commenti.

Nella mia organizzazione agli sviluppatori non è consentito eseguire il QA finale del proprio codice e verificarlo, questo deve essere fatto da un altro sviluppatore. Parte del QA Check è costituito da commenti, quindi nessun commento, nessun check in. Facciamo un sacco di lavoro a contratto in cui la nostra "arte" è in realtà la proprietà intellettuale contrattuale di qualcun altro, quindi gli altri devono essere in grado di comprendere e sfruttare il nostro codice. Inoltre, ci sono momenti in cui i progetti ci ritornano dopo una lunga pausa e dobbiamo essere in grado di raccogliere il codice 18-24 mesi dopo e capire il perché, dove e come siamo arrivati ​​al manufatto del codice di fronte a noi. Ciò fornisce una motivazione egoistica per scrivere commenti di commit.

Chiedi e chiedi ai tuoi colleghi sviluppatori di fare alcune fusioni e di cercare la cronologia e confrontare alcuni file della cronologia.

È probabile che ti chiederanno di inserire commenti il ​​giorno successivo.

Ecco qualche consiglio:

1. Non provare a cambiare il mondo. Fallirai.
2. Invece dovresti riconoscere che tutti funzionano in modo leggermente diverso. Nessuna taglia adatta a tutti.
3. richiedere alcuni passaggi specifici per i processi di lavoro delle persone è molto malvagio. La modifica di questi processi richiede 10 anni. Stai chiedendo loro di farlo prima della prossima scadenza.
4. Anche semplici cambiamenti di processo possono richiedere molto tempo.
5. Qualche piccolo commento sugli commit è troppo insignificante per cambiare questi processi.
6. Puoi presumere che facciano un lavoro di qualità, ma dovrebbero dare abbastanza libertà per scegliere i passaggi stessi. Alcuni passaggi gravosi potrebbero non essere necessari per sviluppatori esperti.
7. Se fai da babysitter ai neofiti, potrebbero essere necessari processi più forti, ma gli sviluppatori esperti non dovrebbero occuparsi di cazzate.
8. Imporre restrizioni draconiane su come il lavoro deve essere svolto non funzionerà mai, può solo rallentare le persone (potrebbe essere buono se sono troppo veloci)
9. Ci sono molte persone che pensano che la loro strada sia l'unico modo giusto per fare le cose. Spero tu non sia uno di loro.

Se il tuo controllo del codice sorgente lo dimostra, attiva i commenti obbligatori per impedire qualsiasi commit non commentato. Abbastanza semplice e tutti si renderanno presto conto che 5 secondi di digitazione di un commento sono indolori.

Ma i commit non commentati sono uno dei più piccoli aspetti negativi che ci siano. Ho partecipato a molti progetti di successo in cui non è stato commentato un singolo commit. Non mettere le mutandine in un mucchio sopra.