Prof. Dr. Pape - Java Programmierrichtlinien - Javadoc

Deutsch

Javadoc - Allgemein

Zurück zur Übersicht

Die durch Javadoc erstellte HTML Dokumentation dient Entwicklern dazu Klassen verwenden zu können ohne die Quelltexte lesen zu müssen oder wenn nur der Bytecode aber nicht die Quelltexte verfügbar sind. Die Javadoc-Kommentare müssen deswegen kurz und spezifisch für alle nicht private Member einer Klasse beschreiben

  • was eine Klasse für eine Menge von Objekten beschreibt
  • was ein Attribute bedeutet und welche Werte es annehmen kann (bzw. nicht darf)
  • was eine Methode macht, was für ein Wert zurückgegeben wird und was die Parameter bedeuten und welche Werte sie annehmen dürfen (bzw. nicht dürfen)

In einem Javadoc-Kommentar sollte nie beschrieben werden wie etwas implementiert ist, es sei denn es ist für die Verwendung der Klasse und deren Objekte notwendig.

Ein Javadoc-Kommentar ist ein mehrzelliger Kommentare der mit /** eingeleitet und mit */ beendet wird. Ob man im Javadoc-Kommentare in jeder Zeile auch noch einen zusätzlichen * hinzufügt oder nicht, ist Geschmackssache. Der erste * in jeder Zeile innerhalb eines Javadoc-Kommentars wird ignoriert. Folgende Varianten sind in der resultierenden HTML-Dokumentation identisch. Man sollte sich generell für eine entscheiden. Am besten die Voreinstellung der Entwicklungsumgebung verwenden.

Kurze und spezifische Kommentare schreiben

Regel: Ein Kommentar muss so kurz wie möglich und spezifisch wie nötig sein.

Begründung

Nur kurze Kommentare werden auch gelesen und nur wenn sie spezifische Informationen haben, dann helfen Sie auch dem Leser. Spezifisch bedeutet mehr Information anzugeben, als im Klassennamen oder der Methodendeklaration enthalten ist: dadurch wird der Kommentar länger. Kurz bedeutet nicht relevante und vor allem unspezifische Informationen wegzulassen.