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&uuml;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&ouml;sungen bzw. L&ouml;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&uuml;gung
  */
public class Mathematik {
  /**
   * @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  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 = b*b-4*a*c;
         if (d>=0){
            if (d==0){
               return("Die Loesung ist: x = " + (-b/(2*a)));
            }
            else{
               return ("x1 = " + ((-b+Math.sqrt(d))/(2*a)) + 
                       ", x2 = " + ((-b-Math.sqrt(d))/(2*a)));
            }
         }
         else{
            return("Die Loesungsmenge ist leer");
         }
      }
   }
  /**
   * @param a Koeffizient des linearen Glieds
   * @param b absolutes Glied
   * @return L&ouml;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&uuml;r die Berechnung des ggT
   * @param b zweite Zahl f&uuml;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&uuml;r die Berechnung des kgV
   * @param b zweite Zahl f&uuml;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) = a*b
      return (a*b)/ggT(a,b);
   }
  /**
   * @param n die Zahl deren Fakult&auml;t berechnet werden soll
   * @return Fakult&auml;t von n
   */
   public static long fakultaet(int n){
      // verwendet wird die rekursive Definition der
      // Fakult&auml;t
      if (n==0) return 1;
      else return n*fakultaet(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