Come faccio a convincere i miei colleghi sviluppatori a VOGLIA di aggiungere commenti al codice sorgente commesso?

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

Potrebbero chiedersi perché il "perché" sia importante ma tra 2 anni quando hai individuato un bug che è un effetto "knock on" di quel cambiamento, sapere perché è stato fatto è incredibilmente importante non solo per correggere il tuo nuovo bug, ma assicurati di non far riemergere il vecchio bug.

C'è anche il motivo dell'auditing. Il binding e l'id del ticket rendono davvero facile dire ok, stiamo spingendo fuori la versione 2, questo corregge i difetti 23, 25, 26 e 27 ma non ci sono commit contro il difetto 24 quindi è ancora eccezionale.

Fagli fare le unioni e gestire il supporto. Anche in questo caso, forse non sei in grado di farlo, ma se ti trovi a dover risolvere un problema da un impegno precedente, invia gentilmente il messaggio oltre la barriera. 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 rami. Non sono sicuro che ti cada o no, ma quella è un'area in cui ho trovato utili i commenti.

Ancora una volta, non nella tua barca, ma quando ho gestito un team di software, ho detto loro che se avessero fatto buoni commenti di commit, avrei usato quelli in liou di un rapporto di stato settimanale. Ho ottenuto ottimi risultati dopo quello ed è stato più facile per me tenere traccia di ciò che stava succedendo anche come manager.

Abbiamo bisogno di commenti di 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 devi confrontare il confronto, ma spesso non lo fai. 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 vedano il valore del tempo di sviluppo.

• Dai il buon esempio. Trasforma i tuoi messaggi di commit in un brillante esempio di utilità. Includere riferimenti a qualsiasi altro sistema utilizzato dal team per gestire storie e difetti. Metti una breve dichiarazione riassuntiva del cambiamento e una buona spiegazione del perché il cambiamento è necessario e non qualcos'altro in ogni sottomissione.
• Ogni volta che la mancanza di un messaggio di commit decente ti causa un lavoro extra, invia una domanda al mittente. Sii persistente con questo (ma non un coglione).
• Se non sta oltrepassando il tuo ruolo, scrivi uno script che manda un log delle modifiche giornaliero usando i messaggi di commit. Ciò darà credibilità al tuo argomento secondo il quale i messaggi utili hanno un vantaggio oltre a sfogliare le revisioni. Ciò potrebbe anche aiutarti a ottenere la gestione dalla tua parte, poiché vedranno giorno per giorno cosa sta succedendo.
• Identifica i tuoi alleati. Speriamo che ci sia almeno un'altra persona che è d'accordo con te (forse in silenzio non è d'accordo). Trova quella persona o quelle persone e convincili ulteriormente in modo da non stare da solo.
• Quando l'opportunità di menzionare quanto i messaggi di commit decenti ti hanno salvato il tempo (o i messaggi scadenti ti hanno costato il tempo) si presenta, prendilo.

Non aver paura di essere la ruota cigolante. Combattere le cattive abitudini delle altre persone è spesso una guerra di logoramento.

Questa deve essere una delle domande più bizzarre che ho sentito. Le persone trascorrono ore o persino giorni a riparare qualcosa e altri 2 secondi per digitare un messaggio di commit è troppo lungo ?! Devo dire che mi preoccuperei di lavorare con persone così miopi. Ovviamente non usano 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 delle versioni non conserva la cronologia delle unioni, quindi per le modifiche precedenti devi trovare il ramo esatto in cui è stato creato, altrimenti il messaggio di commit mostra solo qualcosa come "unito dal ramo Y." Il ramo Y potrebbe mostrare "uniti dal ramo Z" e un ramo in cui alcuni livelli di nidificazione più profondi hanno effettivamente il vero messaggio di commit.

Un nuovo dipendente non sapeva come rintracciare correttamente la cronologia, il che significa che stava essenzialmente lavorando con le differenze. Vide alcuni codici commentati relativi al bug che stava rintracciando. Quando ha decommentato il codice, il suo errore è scomparso. Ha ipotizzato che qualcuno avesse commentato il codice durante il debug e averlo controllato per errore.

Durante la revisione del codice questo non è sembrato giusto a un paio di noi, quindi ho rintracciato il vero messaggio di commit e ho scoperto che c'era un valido motivo 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 vecchio.

Ci sono modi migliori per evitare l'introduzione di questo tipo di regressioni, come test unitari approfonditi, ma in qualche modo non vedo persone che non possono disturbare con un messaggio di commit di 2 secondi che "spreca" il tempo sul test dell'unità.

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

Non c'è nulla che impedisca loro di entrare in 000-0000, ma una volta solo un idiota dirompente sta per creare un numero quando hanno un numero perfettamente accettabile lì.

L'ho fatto dopo aver passato giorni a cercare di trovare in quale build andasse inserita una serie di user story. Sì, si trattava di gestire un fallimento del processo altrove, ma è ancora incredibilmente preziose informazioni da monitorare.

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 una lunga analisi di debug / analisi / indagine dei problemi.

es. ogni volta che passi del tempo a capire qualcosa, come il debugging, l'analisi dei log o qualsiasi altra cosa, 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 risultati.

Tuttavia, la documentazione richiede tempo e, a volte, non è necessario, ad esempio "dovevamo farlo solo una volta, quindi perché annotarlo". 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 per aggiungere commenti di commit, ad esempio almeno il punto al caso / biglietto di Jira che stanno risolvendo, allora potrebbero essere motivati dalla pressione di rispondere costantemente alle domande riguardanti il motivo per ciascun changeset.

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

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

Cerca il perdono, non il permesso.

Mentre duro, ho fatto proprio questo. Ho avuto una divisione 50/50 tra persone che sostenevano e persone che si opponevano, la maggior parte di coloro che 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 sincere).

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

Per una settimana ho ricevuto messaggi come * * (imprecazione cancellata) o kjhfkwhkfjhw. Successivamente, sono stati visualizzati i messaggi di base.

Un anno dopo e gli scettici usano commenti meschini e ammettono in realtà quanto miopi fossero. Non avrei mai potuto ottenere un consenso, ma certamente ho perdonato e forse credibilità. Funziona, le persone lo usano.

Se vuoi essere più congeniale (o ritieni di metterti nei guai), chiedi il permesso di aggiungere un hook di commit per un periodo di prova. Dì che se alla gente non piace in 2 settimane o 4 settimane, lo porterai fuori. Le probabilità sono, perderanno interesse ... o cresceranno piaccia.

Di solito convinco le persone a:

• dialettica con buoni motivi di supporto
• come esempio
• logoramento

Se volessi che la nostra squadra facesse qualcosa di abbastanza grave, continuerei a tormentarmi finché 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.

Altri buoni motivi per commentare i commenti:

• Generazione di ChangeLog automaticamente dai commenti.
• Audit trail per correzioni di bug, aggiunte di funzionalità. Questo è utile sia all'interno che all'esterno del team.
• Rendi più utile la posta di commit.
• Fermami dal chiedere allo sviluppatore che cosa fa l'X (dopo quasi ogni commit).

• Controlla i log SVN per qualcosa di oscuro fatto 6 mesi fa.
• Fai alcune domande su questa cosa senza dire quando è stata fatta
• ???
• Utile

Come fai a vuoi per aggiungere buoni commenti?

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

Quindi - il takeaway - una soluzione potrebbe essere quella di far scrivere agli sviluppatori gli articoli di riepilogo alla fine del progetto che descrivono le modifiche apportate a quali file, quali file sono stati aggiunti / rimossi e perché.

Proponilo alla direzione a porte chiuse:

Lo scenario peggiore si verifica: tutti gli sviluppatori di livello senior escono dalla porta.

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

Chiedigli che cosa pensano renderebbe più facile il loro lavoro ricostruendo la cronologia dell'app:

Leggere semplici commit in inglese che descrivono chiaramente lo stato mutevole del sistema?

O preferirebbero guardare le differenze di codice e capire da soli?

Credo che un modo per convincerli sia quello di provare effettivamente il dolore che senti.

Per esempio, diciamo che stanno lavorando al seguente problema: Hanno un bug che, in qualche modo, è apparso quando è stata implementata un'altra correzione per lo stesso codice (oh l'ironia). Essere in grado di cercare questo dalla semplice ricerca attraverso i messaggi di commit sarebbe fantastico (e quindi scoprire chi lo ha scritto).

Un altro modo sarebbe quello di spiegare loro che il messaggio di commit potrebbe essere utile per dare un suggerimento sul motivo per cui qualcosa è stato implementato in un certo modo. Anche se il messaggio di commit dice semplicemente "funzione X", puoi ancora avere un'idea su chi l'ha implementato, quindi sai con chi parlare.

However, this doesn't seem to be enough to combat the two responses I always get:

1. It takes too long and I just want to get my changes into the repo.
2. It's easy enough to just look at the diffs.

Hai provato a lanciare una sfida ai tuoi colleghi sviluppatori in modo che ottengano qualche altro vantaggio dall'inserimento di commenti? Si potrebbe guardare da entrambi i punti di vista:

1. Upping il loro gioco - Questa può essere la prospettiva più difficile da prendere, ma l'idea qui sarebbe che lo fanno per un certo periodo di tempo e si abituano all'idea in modo che l'abitudine è che ci vorrebbe più tempo per andare dall'altra parte . Un altro punto qui è quanto controllo otterrebbero i commenti? Se desideri una breve storia nel commento, potrei capire il loro punto.
2. Sussidio di un cambiamento - Questo è il punto in cui avresti una sorta di concorso come modo per avere il buy-in iniziale per provare questo o offrire qualche altro tipo di incentivo per fare in modo che il cambiamento venga fatto per un po '. / li>

Qualcos'altro da considerare è quanto bene sai cosa stanno gestendo i tuoi colleghi sviluppatori dove lavori? Se stanno cercando di ottenere 10 cose fatte ieri, 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 potrebbero essere un po 'difensivi o combattivi su questo. Se stai cercando di dire loro, "Mentre questo può funzionare, c'è un'alternativa che potrebbe essere migliore ..." quindi potresti avere una possibilità. Avere un atteggiamento "più santo di te" qui non ti aiuterà, IMO.

Un altro modo di considerare questo è un modo per gli sviluppatori coinvolti per far crescere le loro carriere - dovrebbero possedere il documentazione del loro lavoro.

Oltre agli altri punti sollevati nell'articolo sopra riportato, esiste la possibilità di essere in grado di rivedere le modifiche al codice per scoprire dove / quando / perché è stato effettuato un cambiamento. Potrebbe essere fondamentale quando rintracciare un bug sfuggente.

Dopo averli convinti che è importante commentare i tuoi commit, puoi creare uno script che impone commenti su commit, altrimenti fallirà. Puoi anche specificare un minimo di caratteri per assicurarti un commento significativo. Questo li aiuterà a "ricordare".

Tuttavia, è importante che capiscano il perché, come ha detto @Kevin, altrimenti aggiungeranno commenti casuali.

Hai recensioni di codice? Una cosa che può aiutare è istituire una regola secondo cui qualsiasi commit o fusione deve essere esaminata e approvata da un altro sviluppatore. Quindi se sei il revisore, dovresti chiedere allo sviluppatore di fare il commit per spiegarti cosa ha fatto. Una volta che lo fa, dovresti chiedergli di digitare nel commento ciò che ti ha appena detto. Spesso, quando non è possibile spiegare coerentemente le modifiche apportate, significa che quelle modifiche non avrebbero dovuto essere apportate in primo luogo.

Devo dire però, come possono le persone obiettare a qualcosa che è ovviamente utile come commettere commenti? Non ci vuole molto tempo, ed è un tempo ben speso. Scrivere un commento ti costringe a pensare a quello che hai appena fatto. Potrebbe persino indurti a guardare le differenze per assicurarti di aver effettivamente fatto ciò che pensi di aver fatto e di non aver fatto niente 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.

Dì loro che è l'unico modo per avere la possibilità di mantenere il tuo disordine procedurale di 50.000 metodi di linea, quindi considerare di scrivere un codice migliore e più esplicito in futuro in modo da non dover gestire una serie di commenti inutili che gonfiano il tuo codice base.

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

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

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 in poi.

Ecco alcuni consigli:

1. Non provare a cambiare il mondo. Fallirai.
2. Invece dovresti riconoscere che tutti lavorano in modo leggermente diverso. Nessuna taglia si adatta a tutti.
3. richiedere alcuni passaggi specifici per i processi lavorativi delle persone è molto malvagio. Cambiare questi processi richiede 10 anni. Stai chiedendo loro di farlo prima della prossima scadenza.
4. Anche le semplici modifiche ai processi possono richiedere molto tempo.
5. Alcuni piccoli commenti sui commit sono troppo insignificanti per cambiare questi processi.
6. Si può presumere che facciano un lavoro di qualità, ma dovrebbe dare abbastanza libertà per scegliere i passaggi stessi. Alcuni passaggi onerosi potrebbero non essere necessari per sviluppatori esperti.
7. Se stai facendo da babysitter ai neofiti, allora 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 fatto non ha mai funzionato, 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 di fare le cose. Spero che tu non sia uno di loro.

Se il controllo del codice sorgente lo provi, attiva i commenti obbligatori per evitare committenti non commentati. Abbastanza semplice e tutti presto capiranno che 5 secondi di digitazione di un commento sono indolore.

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