Sollte ich meine Unit-Testmethoden dokumentieren?

8

Als geschieht dies mit privaten Methoden , die Dokumentation zu Komponententestmethoden kann nur gesehen werden, wer Zugriff auf den Quellcode hat. Lohnt es sich, den Aufwand dafür auszugeben?

Mit der Dokumentation meine ich etwas wie (aber beschreibender):

%Vor%     
Jader Dias 08.12.2009, 18:26
quelle

13 Antworten

13

Unit Tests sollten darauf abzielen, selbstbeschreibend zu sein, aber es wird immer Fälle geben, in denen dieses Ziel nicht erreicht werden kann und daher eine Beschreibung dessen, was geschrieben wurde, fällig ist.

Mit anderen Worten, versuchen Sie, Ihre Komponententests so zu machen, dass sie keine Dokumentation benötigen, aber wenn sie sie brauchen, schreiben Sie sie!

    
Vinko Vrsalovic 08.12.2009, 18:30
quelle
13

Ich würde eher geneigt sein zu sagen, dass Sie Ihre Testmethode in einer Weise nennen sollten, die in Bezug auf das, was es testet, ausdrückt: SomeMethodWillBehaveThisWayWhenCalledWithTheseParameters() , obwohl einige Leute das möglicherweise kontrovers finden.

    
Klaus Byskov Pedersen 08.12.2009 18:28
quelle
5

Oh ja!

Auch wenn "wer Zugriff auf den Quellcode hat" nie jemand anderes als Sie sein wird, wird es nicht das gleiche sein, das Sie in einem Jahr (oder sogar in einem Monat) ansehen, vertrauen Sie mir das eine: -)

    
Per Wiklander 08.12.2009 18:31
quelle
2

Sie sollten den gesamten Code dokumentieren.

Bei Komponententests sage ich normalerweise, was ich teste, und wie es getestet wird. "Test for Class.someMethod" ist nicht sehr hilfreich.

    
Ben S 08.12.2009 18:29
quelle
2

Ja. Ich denke, dass das Dokumentieren von Komponententests eine gute Idee ist, wenn Sie während der Entwicklung nicht nur die API Ihrer Produktionsklassen modifizieren, sondern ein internes Verhalten, das einige Tests zum Scheitern bringt, dann spart es eine Menge Zeit für die Navigation Testen Sie den Code, lesen Sie die Dokumentation zum Komponententest und stellen Sie fest, ob Sie erwartet hätten, dass der Test fehlschlägt, wenn Sie sich in letzter Zeit verändert haben oder etwas Subtileres vorkommt.

Ohne diese Dokumentation müssten Sie herausfinden, was der Test mit seinem Namen und den Kommentaren / Codes innerhalb des Tests macht.

Beachten Sie, dass wenn Sie einfach nur den Namen des Unit-Tests in der Dokumentation umschreiben, dies nicht sehr nützlich ist und ich bleibe dabei, dem Komponententest nur einen aussagekräftigen Namen zu geben (dh die Dokumentation sollte es sein) ausführlicher als der Name des Einheitentests)

    
andrew 08.12.2009 19:00
quelle
1

Ich finde es gut, Komponententests zu dokumentieren. Mein Hauptgrund dafür ist, dass Sie erklären können, warum bestimmte Funktionen getestet werden. Meine Komponententests neigen dazu, mit allen möglichen seltsamen extremen oder unerwarteten Parametern zu enden.

Wenn ein Test fehlschlägt, weiß ein zukünftiger Programmierer (oder Sie mit einem schlechten Speicher), warum eine Funktionalität getestet / implementiert wurde.

    
stimpie 08.12.2009 18:31
quelle
1

Ja. Tests mögen sich als selbstdokumentierend erweisen, aber die Faltungen, die Sie manchmal durchlaufen müssen, um aussagekräftige Testdaten zu generieren, bedeuten, dass für den späteren Betreuer, der vielleicht nur SIE ist, nicht alles sofort offensichtlich ist. Machen Sie Ihr Leben einfacher - dokumentieren Sie Ihren Code.

    
Bob Jarvis 08.12.2009 18:32
quelle
1

Ein Komponententest sollte einfach genug und ausführlich genug sein, um das Verständnis zu erleichtern. Wenn Sie Ihren Komponententest kommentieren müssen, sollten Sie vielleicht seinen Namen ändern, oder vielleicht sollten Sie es in kleinere Methoden umgestalten.

Refactoring-Test ist eine gute Übung, Sie müssen Ihre Tests tatsächlich umgestalten, oder sie werden unmöglich zu warten.

Kommentare, wie ich sie sehe, sind fast immer ein Zeichen, dass Sie den Code, den Sie kommentieren müssen, umgestalten sollten. Was für Produktionscode gilt, gilt für Testcode.

    
Stéphane 08.12.2009 18:33
quelle
1

Die meisten Komponententests sollten keine Dokumentation benötigen. Der Name sollte klarstellen, welche Methode sie testen und geben einen Hinweis auf die erwarteten Ergebnisse. Der Code sollte einfach und klar sein. Komponententests sollten keine Geschäftsregeln implementieren, daher ist die Dokumentation des "Warum" normalerweise unnötig.

In dem seltenen Fall, dass ein Test komplex genug sein muss, um Kommentare zu rechtfertigen, sollte er wie jeder andere Code dokumentiert werden.

    
RossFabricant 08.12.2009 18:34
quelle
0

Wenn ich Tests schreibe, favorisiere ich einen Kommentar für den Test, gefolgt von einem aussagekräftigen Namen für die Testmethode (wie das S / S / R-Format in den Kommentaren einer anderen Antwort erwähnt), weil es eine Gewohnheit ist, mit der meine Kollegen und ich zusammenkamen als wir mit CPPUNIT mit C ++ angefangen haben. Während ich in C # experimentiere, ist der von Lucas in seiner Antwort erwähnte Punkt ein guter - wenn das Framework es erlaubt, ist das Beschreibungsfeld, das im Quelltext UND den Ergebnissen verwendet werden kann, sehr praktisch, und ich würde einen Kommentar bevorzugen Format, das an vielen Orten wie diesem verwendet werden kann.

Alles, was gesagt wird, ich denke, Sie müssen sich ansehen, wie Sie oder Ihr Entwicklungsteam normalerweise Code-Kommentare handhaben. Sind Leute im allgemeinen Schwung, wo sie Kommentare aktualisieren, wenn der Code repariert ist, refaktorisiert? Ist das Projekt kleiner und wird es immer die gleichen wenigen Entwickler geben, die eng zusammenarbeiten?

Die Projekte, an denen ich arbeite, sind größer und können je nach Status von einem Team in der Nähe, einem Remote-Team oder gemeinsam entwickelt oder komplett an einen Anbieter übergeben werden. In meinen Szenarien versuchen wir, die Zeit zu verbringen, um die Dokumentation in Produktion und Testcode für diejenigen zu dokumentieren und zu pflegen, die in der Zukunft mitkommen werden.

Wenn Kommentare normalerweise ein Nachdenken sind, so sehr es mich auch schmerzen könnte, wenn es eine Chance gibt, dass Ihre Kommentare mit dem tatsächlichen Code / den Tests nicht mehr aktuell sind, ist es möglicherweise nicht sinnvoll Versuchen Sie, den Status quo zu ändern.

    
dirtybird 10.12.2009 07:57
quelle
0

Für MSTest (IDK, wenn NUnit etwas Ähnliches hat) ist ein DescriptionAttribute für jede Testmethode nützlich, da sie im Panel für Testergebnisse in Visual Studio angezeigt werden. Besser lesbar als die Namenskonvention WhenThisHappenShouldHappenThis.

    
Lucas 08.12.2009 18:38
quelle
0

Ich finde die Nachricht, die durch den Komponententest ausgedruckt wird, wenn sie läuft, im Allgemeinen ausreichend. Zum Beispiel in Perl:

%Vor%

Gibt

%Vor%

bei erfolgreicher Ausführung. Das sagt mir, was ich versuche zu tun, und was die Antwort sein sollte.

    
ire_and_curses 08.12.2009 18:39
quelle
0

Absolut !! Ihre Komponententests sollten genauso gut dokumentiert werden wie Ihr tatsächlicher Code. Aus keinem anderen Grund als dem nicht ungewöhnlichen Umstand, nicht zu wissen, ob es Ihr Code oder Ihr Test ist, der den Bug hat.

    
Ken Lange 08.12.2009 19:27
quelle

Tags und Links