I test unitari sono realmente usati come documentazione?

NON sono una documentazione di riferimento ASSOLUTA

Si noti che molti dei seguenti aspetti si applicano anche ai commenti, in quanto possono non essere sincronizzati con il codice, come i test (anche se sono meno applicabili).

Quindi, alla fine, il modo migliore per capire il codice è avere codice di lavoro leggibile .

^{Se possibile e non scrivendo sezioni di codice a basso livello cablate o condizioni particolarmente difficili, la documentazione aggiuntiva sarà fondamentale.}

• I test possono essere incompleti:
  • L'API è cambiata e non è stata testata,
  • La persona che ha scritto il codice ha scritto i test per i metodi più semplici da testare prima anziché i metodi più importanti da testare e quindi non ha avuto il tempo di terminare.
• I test possono essere obsoleti.
• I test possono essere cortocircuitati in modi non ovvi e non effettivamente eseguiti.

MA SONO ANCORA un complemento di documentazione UTILE

Tuttavia, in caso di dubbi su ciò che fa una particolare classe, specialmente se i commenti piuttosto lunghi, oscuri e mancanti (si conosce il tipo ...), cerco rapidamente di trovare le sue classi di test e controllare:

• quello che cercano effettivamente di controllare (dà un suggerimento sui più importanti bocconcini, eccetto se lo sviluppatore ha fatto l'errore di cui sopra solo implementando i test "facili"),
• e se ci sono casi d'angolo.

Inoltre, se scritto utilizzando uno stile BDD , fornisce una definizione piuttosto buona del contratto della classe . Apri il tuo IDE (o usa grep) per vedere solo i nomi dei metodi e tada: hai un elenco di comportamenti.

Regressioni e bug richiedono test anche

Inoltre, è una buona pratica scrivere test per la regressione e per segnalazioni di bug: si aggiusta qualcosa, si scrive un test per riprodurre il caso. Per esempio, quando si guardano indietro, è un buon modo per trovare la segnalazione di bug pertinente e tutti i dettagli su un vecchio problema, per esempio.

Direi che sono un buon complemento alla documentazione reale e almeno una risorsa preziosa a questo riguardo. È un buon strumento, se usato correttamente. Se inizi a testare presto nel tuo progetto e ne fai un'abitudine, potrebbe essere un'ottima documentazione di riferimento. Su un progetto esistente con cattive abitudini di codifica che già affliggono la base del codice, gestiscile con cura.

Una interpretazione è che i test unitari sono "documentazione eseguibile". È possibile eseguire i test unitari contro il codice e ti dirà se è ancora in esecuzione come era quando i test sono stati scritti per passare, o meno. In questo modo l'unità verifica "documenta" la funzionalità del sistema in un determinato momento, in modo eseguibile.

D'altra parte ho letto solo raramente in realtà il codice del test unitario come "documentazione" per capire la funzionalità. Un test di una singola unità è troppo localizzato, specifico e astratto in modo da essere in grado di dirti molto sul sistema reale che si trova dietro la classe in fase di test.

Se per documentazione intendi voglio che qualcosa scopra come funziona il codice allora i test unitari sono perfetti esempi di come le unità del codice funzionino sia in previsto , casi di edge case e errori (ovvero bug ). Inoltre, i test potrebbero essere creati prima che il codice sia scritto, quindi alla base di ciò che il codice dovrebbe fare dal punto di vista del business / dei requisiti.

Sostituiscono la documentazione? No.

Sono un'utile aggiunta alla documentazione? Sì.

Vedo test unitari come:

• un modo per dimostrare che la documentazione è corretta (supponendo che la documentazione corrisponda all'implementazione API).
• un modo per dimostrare a uno sviluppatore come usare una particolare caratteristica; Gli unit test fixtures / unit test stessi sono di solito abbastanza piccoli da poter essere rapidamente appresi da esso.
• e ovviamente per individuare eventuali bug di regressione.

In qualche modo possono essere visti come complemento di una documentazione esistente ma non come documentazione.

Risponderò alla tua domanda chiedendoti un'altra.

Quante volte, quando lavori con una nuova API / routine, hai attivato l'aiuto per cercare un esempio di codice della cosa che stai tentando di utilizzare? Se non riesci a passare a google per una ricerca online di esempi di codice?

Questo è esattamente quando usereste i test unitari come documentazione.

• In effetti, i test unitari possono essere un po 'più rigorosi dei normali esempi di codice, perché dovrebbe avere più test (esempi).
• Speriamo che i test dell'unità illustrino l'uso appropriato . Per esempio. Mostrano chiaramente tutte le dipendenze essenziali tramite oggetti normali o oggetti finti. (Altrimenti non sono test di unità particolarmente buoni.)
• NOTA: se i tuoi commenti o la "normale documentazione" fornisce esempi di codice, stai violando i principi di DRY. E quegli esempi di codice possono facilmente diventare errati nel tempo, mentre c'è molto meno possibilità di farlo con test unitari eseguiti regolarmente.
• Se i test delle unità sono approfonditi (di solito un grande se ), allora dovrebbero fornire informazioni aggiuntive:
  • Tutti i casi di bordo noti sono chiaramente illustrati.
  • Tutte le eccezioni previste che possono essere generate.
  • Tutti i bug trovati in precedenza (questo è probabilmente più utile quando si estende l'unità in prova piuttosto che quando si scrive un nuovo client per l'unità).
  • Tutte le regole aziendali sottostanti associate all'unità. (se ce ne sono)

Ho il sospetto che ci siano parecchi motivi per cui i test unitari non tendono ad essere usati come documentazione, anche se potrebbero essere un eccellente complemento alla documentazione più tradizionale:

• Mi permetto di suggerire che spesso i test stessi non sono scritti abbastanza bene per lo scopo. Altre risposte hanno già fatto riferimento a test che sono:
  • incompleta.
  • confusione. (Ho visto casi di test che non chiamano direttamente il metodo sotto test - vai a 3/4 livelli in profondità nello stack delle chiamate prima che venga chiamato e le precondizioni per chiamare il metodo sono sparse in punti diversi in una gerarchia di classi complesse. )
  • obsoleto. (Di solito i test dovrebbero fallire quando diventano obsoleti, ma questo non è sempre il caso).
• Di solito ci sono molti esempi di utilizzo già disponibili nel codice di produzione ogni volta che si presenta la necessità di un esempio.
• L'unità in prova è così ben scritta (autodocumentante) che i metodi non hanno bisogno di esempi. Vorrei!
• Nella mia esperienza di programmatore, tendiamo ad essere piuttosto desiderosi di entrare nella parte finale e RTFM martedì prossimo ...
• Documentazione e commenti che violano il principio DRY.

TL; I test delle unità DR e i commenti API sono complementari: alcune cose sono meglio descritte nel codice e altre in prosa.

I test unitari sono principalmente utili per documentare casi speciali e condizioni limite che sono difficili (e ingombranti) da descrivere nei commenti API. Inoltre, i commenti dell'API sono in genere diretti alle persone che desiderano utilizzare l'API.

Se vuoi modificare il codice, di solito c'è molto più che devi sapere, e alcuni di questi sono difficili da inserire nei commenti (e questi commenti diventano rapidamente obsoleti). In tal caso un test unitario funziona anche come documentazione.

Un esempio: hai un metodo m (a, b) che esegue un determinato calcolo. A causa dei requisiti di compatibilità con le versioni precedenti, è necessario che gli input del caso speciale di a=0 e a=-1 , ma solo se b è NULL. Inserirli in un commento è complicato, prolisso e rischia di diventare obsoleto se il requisito viene rimosso in seguito.

Se esegui alcuni test unitari che verificano il comportamento di m(0, NULL) , m(-1, x) ottieni diversi vantaggi:

• La descrizione del comportamento corretto è chiara, le incomprensioni sono ridotte
• Le persone non possono ignorare il requisito quando cambiano il codice, a differenza di un commento