Documentare la causa del bug

Durante l'indagine

Il posto migliore per tenere traccia dei progressi e delle eventuali scoperte tramite i commenti.

L'obiettivo è, dopo tutto, di:

• Assicurati di ricordarti cosa hai fatto ieri quando continui a lavorare sul bug la mattina successiva,

• Assicurati che i tuoi colleghi possano subentrare se, per qualche motivo, dovresti interrompere il lavoro sul bug.

Se nel primo caso, la posizione non ha importanza, nella seconda, il thread di discussione dei bug è il posto naturale in cui gli sviluppatori andrebbero a prendere le ultime informazioni.

Una volta risolto il bug

Il luogo ovvio da usare per documentare la risoluzione di un bug sarebbe il commit che risolve il bug , e talvolta il messaggio di commit.

Nella maggior parte dei casi, questo è tutto ciò che serve ad altre persone per capire in seguito cosa ha causato l'errore. Se il codice non è semplice e non fa in modo che il bug si ripercuota chiaramente su una persona che guarda il diff, è probabile che sia necessario rifattorizzare il codice per renderlo più esplicito o aggiungere un commento.

Una delle ragioni è che (1) se il bug esistesse in primo luogo e (2) se la differenza tra il vecchio e il nuovo codice non chiarisce perché il bug esisteva in precedenza, allora c'è un rischio per qualcuno di reintrodurre il bug più tardi.

A volte, tuttavia, il bug è così strano che nessun commento sul codice può chiarire. In questo caso, i campi di discussione sono davvero un buon posto per quei dettagli. Il ticket originale descrive il comportamento atteso e osservato; i commenti spiegano cosa succede sotto il cofano.

Esempi

Molte segnalazioni di bug su GitHub sono una buona illustrazione:

• Il ticket stesso descrive il problema.
• I commenti spiegano le scoperte, aggiungono i dettagli (casi limite, possibili regressioni da qualche altra parte quando si tenta di risolvere un bug, ecc.), e spesso la risoluzione stessa, prima che il bug sia effettivamente risolto. Quello che succede, a volte, è che qualcuno sa come risolvere un bug, ma non ha necessariamente il tempo di fare la vera codifica.
• Il numero di revisione del commit che ha risolto il problema.

Git Hub può essere un buon posto per documentare e identificare il problema, ma un posto migliore per documentare il bug è con un test:

describe('MyMethodWithBug - #123456')
  it('should do something that its not currently doing with this data')
     result = MyMethodWithBug(data)
     assert.that(result).eq.(correctResult)

Il test dovrebbe fallire fino a quando il bug non viene corretto. E ora hai documentato questo comportamento per te e per i futuri sviluppatori.

Nella maggior parte dei casi che ho visto negli ultimi decenni, dopo aver scoperto la causa principale di un problema, il duro lavoro è stato fatto. La correzione del bug poteva essere eseguita spesso in alcuni minuti o ore, in realtà non era necessario documentarlo in alcun modo prima che inizia a risolvere il bug. Quindi quando chiedi dove è "solitamente documentato", la risposta è

• solitamente da nessuna parte (nel sistema di rilevamento dei problemi)

Spesso non vale la pena documentare la causa alla radice in un tracker di problemi prima che il problema venga risolto, poiché ciò porta alla documentazione ridondante, prendendo i registri di commit della correzione di bug e la documentazione in-code come pure i test in considerazione che vengono creati durante il risolimento . Se hai bisogno di tracciabilità, puoi anche fare riferimento all'id del problema in quei commenti.

Anche quando è necessario un appunto per "continuare a lavorare sul bug la mattina successiva" (come Arzeni Mourzenko ha scritto ), non vedo alcuna necessità di inserire tali note nel tracker dei problemi. Un pezzo di carta o un oggetto nel tuo pianificatore di attività elettronico personale o un semplice file di testo (tutto ciò che può essere scaricato quando la risoluzione è stata completata) sarà sufficiente. Lo stesso vale per le informazioni che devi fornire agli altri membri del team quando devono contribuire alla risoluzione: email, un forum di discussione elettronico o un commento "TODO" usa e getta nel codice è probabilmente sufficiente per questo.

Naturalmente, ho anche visto casi in cui un bug non poteva essere risolto così rapidamente e la risoluzione doveva essere suddivisa in diversi passaggi (ognuno dei quali valeva un ticket). In questi casi, i nuovi ticket funzionano come la documentazione richiesta.

Se non è possibile correggere un bug senza interrompere altre parti del software (ad esempio, la retrocompatibilità), il ticket verrà chiuso senza ulteriori azioni. Questo è l'unico caso a cui posso pensare dove è richiesta una voce aggiuntiva di documentazione nel sistema di tracciamento dei problemi. La maggior parte dei tracker di problemi che ho visto consentono di aggiungere un "motivo di chiusura", quindi inseriscilo qui.