6.9.2
Dokumentationskommentare im Java-Quelltext |
|
Dokumentation des Quell- textes | Java
unterscheidet drei Arten von Kommentaren, die man in den Quelltext eines Programms
einfügen kann. 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, nennen
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 das Arbeiten am Quelltext erleichtert, stehen in Java zwei Arten von "Kommentarklammern" 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 ein 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. Wir zeigen dies an einem Beispiel. |
@version, @author, @param, @return | @version,
@author, @param, @return sind standardisierte Marker.
@version und @author werden im Kopf
der Klasse, genauer vor der ersten Quelltextzeile der Klasse gesetzt, mit
ihrer Hilfe kann man Mitteilungen ü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 März 2005 * @author Michael Pohlig.<br> * Diese Klasse stellt eine Reihe <B>mathematische * Werkzeuge</B> * zur Verfügung */ public class Mathematik { ... Eingeleitet wird dieser Kommentar mit '//*'. Jeder Zeile ist ein '*' vorgesetzt und der Kommentar wird mit '*/' beendet. |
|
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. Für jeden übergeben Parameter benötigen wir eine solche Zeile | |
/** * @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){ ... } |
|
Zur Übung
vervollständige man die Dokumentation im Quelltext von
Mathematik.java
in seiner letzten Version. Lösung:
|
|
Im
Menüpunkt 'start' des Javaeditors findet sich die Zeile JavaDoc:
Klickt man JavaDoc an, so wird
javadoc.exe,
also das Programm, das eine API-Dokumentation erstellt, gestartet.
|
|
zu | 6.9.3 Dokumentation der Klasse Mathematik |
zur Startseite | www.pohlig.de (C) MPohlig 2005 |