Scrivere commenti java doc per casi di test unitari

A mio avviso, i casi di test unitari servono come documentazione per il codice. La mia azienda vuole che scriva commenti dettagliati su java doc in cima ai casi di test unitari. È necessario farlo? Scrivi commenti del genere?

unit-testing documentation

— Vinoth Kumar CM
fonte

supponendo che il codice del test sia ben scritto e leggibile, il valore principale di un commento di questo tipo nel codice del test è come una dichiarazione di intenti .. Questo può essere molto utile per i revisori del codice, anche per te stesso tra un anno, in quanto ti consente giudicare il codice che è stato scritto sta facendo ciò che dovrebbe fare, o testando ciò che dovrebbe testare. In secondo luogo è possibile utilizzare sistemi come JAVADOC o anche un semplice script per eliminare i nomi dei test e i commenti dal codice per creare un breve pezzo di documentazione su quali test hai e cosa stanno facendo.

— Chuck van der Linden,

Risposte:

Quello che faccio è il commento di JAVADOC:

la classe, indicando quale classe è unit test (anche se dovrebbe essere ovvio poiché la migliore pratica su tale argomento suggerisce che il nome del caso di test dovrebbe essere il nome della classe + "Test" o + "TestCase"). Questo viene fatto usando il commento JAVADOC {@link XXXClass}
i metodi, indicando quale metodo è stato testato ({@link XXXClass # method1}). A volte ho bisogno di avere più metodi di prova per un metodo di una classe per testare correttamente tutti i percorsi. Quando succede, scrivo una riga aggiuntiva indicando quale percorso sto testando all'interno (ma non mi allontano mai dalla mia convenzione di una riga)

A parte questo, nessun altro commento. Per attirare la loro attenzione altrove, forse potresti usare qualcosa come Cobertura per generare graziose grafiche con copertura del codice e renderle felici in quel modo :-)

Nota aggiuntiva: mi riferisco ai casi di test unitari, se stiamo parlando di casi di test di integrazione, allora potrebbero essere necessarie una o due righe in più per spiegare cosa sta succedendo ...

— Jalayn
fonte

I requisiti di documentazione per qualsiasi codice sono abbastanza completamente coperti nelle risposte a questa domanda: il mio capo vuole una spiegazione inglese narrativa riga per riga del nostro codice

Come riepilogo delle risposte che vedrai lì, "Dipende dalla tua situazione". Ci sono casi in cui è ragionevole (e incoraggiato) e altri in cui è una perdita di tempo.

— blueberryfields
fonte

I commenti Javadoc possono essere estratti e formattati in un documento di riferimento separato, i test unitari no. Inoltre, tieni presente che ciò che scrivi a parole può essere diverso dal codice reale e di solito stai descrivendo a parole il comportamento atteso reale. Uno dei modi per trovare i bug è quello di confrontare la documentazione con il codice reale, se non corrispondono - è un bug (in uno di essi, e talvolta - entrambi).

Il test unitario è per i test, non per la documentazione. L'uso del test unitario come documentazione è errato e non dovrebbe essere eseguito.

— littleadv
fonte

Trovo che una buona serie di test unitari sia estremamente utile nella documentazione del codice. Forniscono un'implementazione di riferimento su come il codice di qualcuno dovrebbe essere usato, insieme alla prova che il codice si comporta correttamente quando usato in quel modo.

— Bill Michell,

@Bill - nessun argomento a riguardo, è utile. Non sostituisce la documentazione corretta.

— littleadv,

Dipende dal pubblico per la tua documentazione, ma in alcuni casi hai sicuramente ragione.

— Bill Michell,

Idealmente , i test unitari non dovrebbero essere l'unica documentazione di un sistema, ma nel mondo reale, 9 progetti su 10 stanno lavorando con un codice legacy in cui può essere considerato fortunato avere qualsiasi documentazione. E in questo caso, preferisco una buona serie di test unitari in esecuzione e passati su un mucchio di documenti che potrebbero essere totalmente fuori sincrono con il codice reale. (Sì, anche il Javadoc può.)

— Péter Török,

@ PéterTörök Sì ... Mi sono trasferito tra diversi datori di lavoro, alcune aziende molto conosciute. Un sacco di codice legacy. Le uniche unit test di sempre - quelle che ho scritto. Quindi sei stato molto molto fortunato. Non dare per scontato che ciò che hai visto sia ciò che accade ovunque. E anche se hai una serie di test unitari ... Chi ha detto che sono corretti? Chi ha detto che coprono ciò che dovrebbero? Chi ha detto che i risultati attesi sono quelli che sono? Perché supponi che i test unitari non siano fuori sincrono? Solo perché "passano"? Senza senso.

— Littleadv,