Sollte JUnit-Tests javadocced werden?

Question

Ich habe eine Reihe von JUnit-Testfällen, die derzeit nicht mit Javadoc Kommentaren dokumentiert.

Der Rest meines Code ist dokumentiert, aber ich frage mich, ob es auch die Mühe wert, diese Tests zu dokumentieren.

Answer 1

Wenn der Zweck des Tests liegt auf der Hand, ich Mühe, es nicht zu dokumentieren.

Wenn es nicht offensichtlich, weil es mit einiger obskuren Situation beschäftigt - oder wenn ich auf einen bestimmten Fehler beziehen möge, zum Beispiel - in , die Fall werde ich Dokumentation hinzufügen. Ich dokumentiere nicht Ausnahmen obwohl etc werfen - nur eine kurze Zusammenfassung des Verfahrens. Dies geschieht relativ selten. Ich bin eher Dokumentation für Hilfsmethoden in mehreren Tests verwendeten hinzuzufügen.

Answer 2

Ich finde keinen Wert in javadocing die Testfälle. Ich mache nur den Namen der Methode beschreibend genug, um den Zweck des Tests zu kennen.

In Ruby, ich weiß, gibt es Tools, um ein Dokument aus dem Namen der Tests zu erstellen, aber ich habe nicht ein von diesem in Java zu sehen.

Answer 3

Ob javadoc oder nicht, denke ich, dass Unit-Tests auf jeden Fall dokumentiert werden sollen. In Fällen, in denen keine formale Spezifikation, so sind die Unit-Tests, was am nächsten kommt das erwartete Verhalten des Codes zu definieren. Durch die Dokumentation der Testfälle, werden Sie es dem Leser klar machen, was der Test-Tests ist, und warum es zu testen es.

Answer 4

Wenn über die Tests als Dokumentation zu denken, ist es nicht viel Sinn „Dokument der Dokumentation“ machen. Der Name jeder Test sollte in sich bereits die beschreiben, was der Zweck der Tests ist -. Was ist das Verhalten von diesem Test angegeben werden

Verwenden Sie lange, beschreibenden Namen für die Tests, und halten Sie den Testcode so lesbar wie möglich.

Zum Beispiel hat einen Blick auf den Testfällen in diesem Projekt . Hat einer von ihnen etwas tun, das, indem man die Namen der Tests und der Testcode nicht ganz offensichtlich ist?

Es ist nur in seltenen Fällen, wenn der Testcode dunkel ist, dass die Kommentare in Tests benötigt werden. Zum Beispiel, wenn Sie Multi-Threaded-Code testen und der Testcode tut seltsame Dinge, um sicher zu stellen, dass der Testcode in der richtigen Reihenfolge ausgeführt wird. Aber auch in diesen Fällen ein Kommentar ist eine Entschuldigung nicht sauberen Testcode zu schreiben.

Answer 5

Ich sehe nicht, warum Sie Testfälle anders als Ihr Produktionscode in Bezug auf Kommentare behandeln sollen.

Answer 6

Ich denke, es zu javadoc wertvoll die Bedingungen, unter denen die Prüfungen bestehen.

Answer 7

Ist es Ketzerei zu behaupten, dass Code Kommentare sind ein Anti-Muster? Ich stimme mit den oben genannten Antworten, idealerweise Ihr Code genug beschreibend sein würde, ohne Kommentare zu verlassen. Dies gilt insbesondere, wenn Sie in einer (Enterprise) Umgebung sind, wo Menschen neigen dazu, den Code zu aktualisieren, ohne Kommentare zu aktualisieren, um Kommentare irreführend sein.

Answer 8

Hölle ja. Wenn es auch nur ...

erstellen, um, zu bearbeiten, um, speichern, laden und überprüfen Sie es.

Wenn es einen wirklich einfacher Test, dann vielleicht auch nicht.

Ich finde, dass als Codeänderungen, manchmal der Grund für den Test nicht offensichtlich ist, wie es einmal war.

Answer 9

Vielleicht könnten Sie jemanden, der nicht ganz vertraut mit Ihrem Code ist es, Ihnen ein paar schnelles Feedback zu geben, ob die Tests leicht verständlich sind, wie sie sind.

Bei der Firma für die ich arbeite, versuchen wir unseren Tests beschreibende Namen und Komplexität der jeweiligen Dokument zu geben, aber es ist oft schwer, diese „richtig“ zu erhalten mit dem ersten Entwurf, weil die Dinge, die den Entwickler offensichtlich sind, sind nicht immer klar, andere.

Die Prüfungen werden wie Code behandelt und im Rahmen eines Peer-Review-Prozesses, so dass unser (small) Team kann, ob ein Test leicht zu verstehen oder nicht äußern eingereicht.

Wenn ein Test ein wenig verwirrend ist, können wir den Namen oder die Dokumentation entsprechend aktualisieren und wir kommen weg mit einer besseren Lehre von dem, was funktioniert und was nicht.