Schreiben von Java Doc-Kommentaren für Unit-Testfälle

Meiner Meinung nach dienen die Unit-Testfälle selbst als Dokumentation für den Code. Mein Unternehmen möchte, dass ich detaillierte Kommentare zu Java-Dokumenten über Unit-Testfälle schreibe. Ist das notwendig? Schreibst du solche Kommentare?

unit-testing documentation Vinoth Kumar CM
quelle

Vorausgesetzt, der Testcode ist gut geschrieben und lesbar, ist der Hauptwert eines Kommentars dieser Art im Testcode eine Absichtserklärung. Dies kann für Code-Prüfer sehr wertvoll sein, selbst für Sie in einem Jahr, wenn es Ihnen erlaubt Zu beurteilen, welcher Code geschrieben wurde, bedeutet, das zu tun, was er tun soll, oder zu testen, was er testen soll. Zweitens können Sie Systeme wie JAVADOC oder sogar ein einfaches Skript verwenden, um die Testnamen und Kommentare aus dem Code zu entfernen und eine kurze Dokumentation darüber zu erstellen, welche Tests Sie haben und was sie tun.

Chuck van der Linden

Antworten:

Was ich mache ist JAVADOC-Kommentar:

die Klasse, die angibt, welche Klasse Unit-getestet ist (obwohl es mir klar sein sollte, da die Best Practice zu diesem Thema vorschlägt, dass der Name des Testfalls der Name der Klasse + "Test" oder + "TestCase" sein sollte). Dies erfolgt mit dem JAVADOC-Kommentar {@link XXXClass}
die Methoden, die angeben, welche Methode getestet wird ({@link XXXClass # method1}). Manchmal brauche ich mehrere Testmethoden für eine Methode einer Klasse, um alle Pfade richtig zu testen. Wenn es passiert, schreibe ich eine zusätzliche Zeile, in der angegeben ist, welchen Pfad ich im Inneren teste (aber ich weiche nie von meiner einzeiligen Konvention ab).

Ansonsten kein weiterer Kommentar. Um ihre Aufmerksamkeit woanders zu lenken, könnten Sie vielleicht etwas wie Cobertura verwenden , um hübsche Grafiken zur Codeabdeckung zu generieren und sie auf diese Weise glücklich zu machen :-)

Zusätzlicher Hinweis: Ich beziehe mich auf Unit-Testfälle. Wenn es sich um Integrationstestfälle handelt, sind möglicherweise ein oder zwei weitere Zeilen erforderlich, um zu erklären, was vor sich geht.

Jalayn
quelle

Die Dokumentationsanforderungen für jeden Code werden in den Antworten auf diese Frage ziemlich vollständig behandelt: Mein Chef möchte eine ausführliche englische Erklärung unseres Codes

Als Zusammenfassung der Antworten sehen Sie dort "Es hängt von Ihrer Situation ab". Es gibt Fälle, in denen dies angemessen (und empfohlen) ist, und andere, in denen es Zeitverschwendung ist.

Blaubeerfelder
quelle

Javadoc-Kommentare können in einem separaten Referenzdokument extrahiert und formatiert werden, Unit-Tests jedoch nicht. Denken Sie auch daran, dass das, was Sie in Worten schreiben, vom tatsächlichen Code abweichen kann und Sie normalerweise das tatsächlich erwartete Verhalten in Worten beschreiben. Eine Möglichkeit, Fehler zu finden, besteht darin, die Dokumentation mit dem tatsächlichen Code zu vergleichen, wenn sie nicht übereinstimmen - es handelt sich um einen Fehler (in beiden Fällen und manchmal auch in beiden Fällen).

Unit-Test dient zum Testen, nicht zur Dokumentation. Die Verwendung des Komponententests als Dokumentation ist falsch und sollte nicht durchgeführt werden.

littleadv
quelle

Ich finde eine gute Reihe von Unit-Tests immens hilfreich bei der Dokumentation von Code. Sie bieten eine Referenzimplementierung, wie Code jemand sollte verwendet werden, zusammen mit dem Nachweis , dass die Code verhält sich richtig , wenn auf diese Weise verwendet wird .

Bill Michell

@ Bill - kein Argument dafür, es ist hilfreich. Es ersetzt nicht die richtige Dokumentation.

littleadv

Hängt bei Ihrer Dokumentation vom Publikum ab - aber in einigen Fällen sind Sie definitiv richtig.

Bill Michell

Im Idealfall sollten Unit-Tests nicht die einzige Dokumentation eines Systems sein - aber in der realen Welt arbeiten 9 von 10 Projekten mit Legacy-Code, bei dem es als Glücksfall angesehen werden kann, überhaupt eine Dokumentation zu haben. In diesem Fall bevorzuge ich eine Reihe von laufenden und bestandenen Komponententests gegenüber einer Reihe von Dokumenten, die möglicherweise nicht mit dem tatsächlichen Code synchron sind. (Ja, sogar der Javadoc kann.)

Péter Török

@ PéterTörök Ja ... Ich bin zwischen verschiedenen Arbeitgebern gewechselt, einigen sehr bekannten Unternehmen. Viel Legacy-Code. Die einzigen Unit-Tests, die ich je geschrieben habe. Sie hatten also sehr viel Glück. Gehen Sie nicht davon aus, dass das, was Sie gesehen haben, überall passiert. Und selbst wenn Sie eine Reihe von Unit-Tests haben ... Wer hat gesagt, dass sie korrekt sind? Wer hat gesagt, dass sie abdecken, was sie sollten? Wer hat gesagt, dass die erwarteten Ergebnisse so sind, wie sie sind? Warum gehen Sie davon aus, dass die Komponententests nicht nicht synchron sind? Nur weil sie "passen"? Unsinn.

littleadv