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 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ü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ö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ösungen bzw. Lö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 |