21

21.2 Dokumentationskommentare im Java-Quelltext
Dokumentation des Quell- textes	Java unterscheidet drei Arten von Dokumentationen eines Programms. 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 "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. 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 Februar 2003 * @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. /** * @version 2.0 Februar 2004 * @author Michael Pohlig.<br> * Diese Klasse stellt eine Reihe <B>mathematischer * Werkzeuge</B> * zur Verfügung / public class Mathematik { /* * @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 ax^2 + bx +c =0 / public static String loeseQuadGl(double a, double b, double c){ if (a==0){ if (b==0){ if (c==0){ return("alle reellen Zahlen sind Loesungen"); } else{ return("Die Loesungsmenge ist leer"); } } else { return("Die Loesung ist x = " + (-c/b)); } } else{ double d = bb-4ac; if (d>=0){ if (d==0){ return("Die Loesung ist: x = " + (-b/(2a))); } else{ return ("x1 = " + ((-b+Math.sqrt(d))/(2a)) + ", x2 = " + ((-b-Math.sqrt(d))/(2a))); } } else{ return("Die Loesungsmenge ist leer"); } } } /* * @param a Koeffizient des linearen Glieds * @param b absolutes Glied * @return Lösung der linearen Gleichung ax + b = 0 / public static String loeseGl(double a, double b){ if (a!=0)return "Loesung ist: "+ -b/a; else { if (b!=0) return "Loesungsmenge ist leer"; else return "Loesungsmenge ist ganz R"; } } /* * @param a erste Zahl für die Berechnung des ggT * @param b zweite Zahl für die Berechnung des ggT * @return ggT(a,b) / public static int ggT(int a, int b){ // verwendet wird der rekursive Euklidsche Algorithmus if(a==b\|\|b==0) return a; else return ggT(b,a%b); } /* * @param a erste Zahl für die Berechnung des kgV * @param b zweite Zahl für die Berechnung des kgV * @return kgV / public static int kgV(int a, int b){ // verwendet wird der Satz ggT(a,b) kgV(a,b) = ab return (ab)/ggT(a,b); } /** * @param n die Zahl deren Fakultät berechnet werden soll * @return Fakultät von n / public static long fakultaet(int n){ // verwendet wird die rekursive Definition der // Fakultät if (n==0) return 1; else return nfakultaet(n-1); } /** * @param n die Zahl zu der die Fibonacci-Zahl berechnet werden soll * @return Fibonacci von n / public static long fibonacci(int n){ // verwendet wir die explizite Darstellung der Fibonacci-Zahl // was wesentlich effizienter ist return (long)(1/Math.sqrt(5) (Math.pow((1+Math.sqrt(5))/2,n)- Math.pow((1-Math.sqrt(5))/2,n))); } }
	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	21.3 Dokumentation der Klasse Mathematik
zur Startseite	www.pohlig.de (C) MPohlig 2004