15.2 Dokumentationskommentare im Java-Quelltext
 
Dokumentation des Quell- textes Wir beginnen damit zu zeigen, wie man einen Quelltext so dokumentiert, dass er auch von Programmieren leicht verstanden werden kann, die den Originaltext nicht erstellt haben. Beim professionellen Programmieren ist das sehr wichtig. Man mache sich folgende Situation klar. En Programmierer, nenneb wir ihn der Einfachheit halber "A", erstellt den Quelltext eines Programms. Nun kann es passieren, dass er eine geraume Zeit später erneut an diesem Quellcode arbeiten soll. Eine Quelltext-Dokumentation seines Textes erleichtert dieses Unternehmen erheblich. Oft kann man die Gedanken, die man sich beim Programmieren gemacht hat, aus dem reinen Quelltext nicht mehr rekonstruieren. Noch schwieriger wird die Situation, wenn "A" durch Krankheit, Tod oder berufliche Veränderung ausfällt, der Quelltext also von einer anderen Person "B" bearbeitet werden soll.

Für die Dokumentation des Quelltextes, die also das Arbeiten am Quelltext erleichtert, stehen in Java zwei Arten von "Dokumenationsklammern" zur Verfügung, die uns schon teilweise begegnet sind.

//Dies ist ein Kommentar, der mit der Zeile, in der
//er steht, automatisch endet, also keine "Klammer-zu"
//benötigt.

Der Kommentar wird mit zwei Schrägstrichen eingeleitet. Soll ein solcher Kommentar über mehrere Zeilen gehen, muss jede Zeile mit // eingeleitet werden.

Daneben gibt es die Möglichkeit Kommentare über einen definierten Bereich zu setzen:

/* hier ist ein Kommentar,
   hier ist immer noch Kommentar
   und hier endet er:
*/

Der Kommentar kann mit der /*.....*/ aber auch ganz anders eingesetzt werden. Dies zeigt z.B. ihr Einsatz im Kopf einer Schleife, in der mittels eines Kommentars ein Teil des Quelltextes für den Compiler ausgeblendet wird:.

while(i<20 /* && k!=10 */) {...}

Veränderungen des Quelltextes können so einfach vorgenommen und wieder zurückgesetzt werden. Ein beliebtes Verfahren bei der Fehlersuche.

 

Dokumenation mit javadoc.exe Eine dritte Variante der Kommentarklammerung bereitet den Einsatz von javadoc.exe vor. Sie dient für dem Anwender der Klasse, den nicht der Quelltext der Klasse Mathematik sondern die Funktionalität der Methoden der Klasse Mathematik interessiert. Wir zeigen an einem Beispiel, wie man mit javadoc.exe arbeitet.
@version, @author, @param, @return Die Marker @version, @author, @param, @return sind standardisiert. @version und @author werden im Kopf der Klasse, genauer vor der ersten Quelletxtzeile der Klasse gesetzt, sie geben Auskunft über die Versionsnummer und den Autor der Klasse.  Weitere Informationen können hinzugefügt werden. Dabei ist es sinnvoll, html-Tags zu benutzen, um den Text besser strukturieren und einzelne Wörter hervorheben zu können.
 
/**
  * @version 1.0  Februar 2003
  * @author Michael Pohlig.<br>
  * Diese Klasse stellt eine Reihe <B>mathematische
  * Werkzeuge</B>
  * zur Verf&uuml;gung
  */
public class Mathematik {
  Vor jeder Methode werden Erklärungen eingefügt, wie z.B. Informationen über die übergebenen Parameter und den Rückgabewert.  Dem 'Schalter' @param folgt nach einem Leerzeichen der Name des Parameters und nach einem weiteren Leerzeichen die Erläuterung.  
 
 /* Der Algorithmus berechnet reelle L&ouml;sungen der
    Gleichung ax^2 +bx + c = 0
 */
 /**
  * @param a Koeffizient des quadratischen Glieds
  * @param b Koeffizient des linearen Glieds
  * @param c absolutes Glied
  * @return L&ouml;sungen bzw. L&ouml;sungsmengen der 
  * quadratischen Gleichung
  */
 public static String loeseQuadGl(double a,double b,double c){
   ...
 }
  ...
}
Mathematik. java Zur Übung vervollständige man die Dokumentation im Quelltext von Mathematik.java in seiner letzten Version.
  Das Programm javadoc.exe lässt sich auch aus der Entwicklerumgebung JavaEditor direkt starten. Dazu klickt man auf JavaDoc im Start-Menü des JavaEditors.

 

 

 

  javadoc.exe erzeugt aus dem aktiven Java-Quelltext in dem Verzeichnis, in dem auch dieser Quelltext abgelegt ist, ein Unterverzeichnis Doc<name_der_Klasse>, in dem eine Reihe von verlinkten HTLM-Seiten abgelegt wird. Wenn in der Konfiguration des JavaEditors die Option  IExplorer intern benutzen gesetzt ist, wird die HTML-Dokumentation im Browser-Fenster des JavaEditors auch gleich dargestellt. Sonst kann man die Dokumentation mit einem beliebigen Browser starten. Als "Startdatei" verwende man index.html.
zu 15.3 Dokumentation der Klasse Mathematik
zur Startseite www.pohlig.de  (C) MPohlig 2003