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
//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 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&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.

Lösung:

/**
  * @version 2.1  M&auml;rz 2005
  * @author Michael Pohlig.<br>
  * Diese Klasse stellt eine Reihe <B>mathematischer
  * Werkzeuge</B>
  * zur Verf&uuml;gung
  */
public class Mathematik {

  /**
   * L&ouml;st die quadratische Gleichung ax² + bx + c =0
   * @param a Koeffizient in  <b>a</b>x² + bx + c =0
   * @param b Koeffizient in  ax² + <b>b</b>x +c =0
   * @param c absolutes Glied in ax² + bx + <b>c</b> =0
   * @return L&ouml;sungen bzw. L&ouml;sungsmengen
   * quadratischen Gleichung
   */
  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");
      }
    }
  }
  
  /**
   * L&ouml;st die lineare Gleichung ax + b = 0
   * @param a Koeffizient in <b>a</b>x + b = 0
   * @param b absolutes Glied in ax + <b>b</b> = 0
   * @return L&ouml;sung bzw. L&ouml;sungsmenge
   */
  public static String loeseLinGl(double a, double b){
    // Die Methode verwendet die Methode loeseQuadGl
    return loeseQuadGl(0, a, b);
  }

  /**
   * berechnet den ggT(a,b)
   * @param a erste Zahl f&uuml;r die Berechnung des ggT(<b>a</b>,b)
   * @param b zweite Zahl f&uuml;r die Berechnung des ggT(a,<b>b</b>)
   * @return den ggT
   */
  public static int ggT(int a, int b){
     // verwendet wird der erweiterte Euklidsche Algorithmus
    if(a==b||b==0) return a;
    else return ggT(b,a%b);
  }

  /**
   * berechnet den kgV(a,b)
   * @param a erste Zahl f&uuml;r die Berechnung des kgV(<b>a</b>,b)
   * @param b zweite Zahl f&uuml;r die Berechnung des kgV(a,<b>b</b>)
   * @return das 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);
  }
  
  /**
   * Berechnet Fakult&auml;ten n!
   * @param n die Zahl deren Fakult&auml;t berechnet werden soll
   * @return 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);
  }
  
  /**
   * Berechnet Fibonacci-Zahlen
   * @param n die Zahl zu der die Fibonacci-Zahl berechnet werden soll
   * @return Fibonacci von n
   */
  public static long fibonacci(int n){
      // verwendet wird 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 6.9.3 Dokumentation der Klasse Mathematik
zur Startseite www.pohlig.de  (C) MPohlig 2005