Kommentierung

Inhalt:

Allgemein

    //regulärer Ausdruck für benutzerdefinierte Eingaben
    private Regex neuerReg = new Regex("\\$(?<Tag>[^\\[]*)\\[(?<Typ>[^\\]]*)\\]\\$");

• Klassen-Kommentare: beschreiben die Klassen im Überblick.
• Methoden-Kommentare: beschreiben die einzelnen Methoden im Detail
• Kommentare innerhalb des Code: diese sind für den Nutzer einer Library unwichtig, aber sinnvoll für den, der sich mit dem Quellcode befassen muss.

Projekt-Überblick-Datei

Package-Kommentare

/**Erklärungen zum Package oder zur Anwendung...
 *  
 * @author Ich war's!
 *
 */
package de.hs_rm.cs.bla.fasel;

Klassen-Kommentare

• Guter Grobüberblick: Der Kommentar gibt hauptsächlich ein Kurzüberblick über die möglichen Methoden, wodurch man alles schnell erfassen kann.
  
• Grundlegende Konzepte: Im Klassenkommentar wird erklärt, was in den folgenden Methoden z.B. unter einem "Whitespace" zu verstehen ist.
  

• Erzeugung von Instanzen: Der Kommentar weißt darauf hin, dass man Instanzen idealerweise über static Methoden erzeugt.
• Funktionsweise: Die Datumsformate werden sehr detailliert beschrieben, einschließlich Beispielen.

• Klassenüberblick: hier ist in Fließtext-Form die grundlegende Verwendung der Klasse beschrieben.
• Besonderheiten bei der grundlegenden Verwendung der Klasse: es wird einigermaßen detailliert auf "initial capacity" und "load factor" eingegangen.
• Besonderheiten bei einzelnen Aspekten der Klasse: es wird explizit darauf hingewiesen dass der Iterator-Aspekt des Hashtable unter gewissen Umständen gefährlich sein kann.

• Einen Überblick über die Verwendung geben.
• Erklären, wie man an Instanzen der Klasse kommt (falls es nicht über einen Standard-Konstruktor geht)
• Grundkonzepte der Klasse erklären
• Sonstige wichtige Informationen über die Klasse geben (z.B. Performanz-Betrachtungen, Beziehung zu anderen Klassen)

Methoden-Kommentare

  /**
   * Berechnet ein Quader-Volumen
   * 
   * @param a Seite a
   * @param b Seite b
   * @param c Seite c
   * @return Volumen
   * @exception InvalidParameterException
   */
  public double computeCuboidVolume(double a, double b, double c) throws InvalidParameterException

  /**
   * Berechnet ein Quader-Volumen nach der Formel "a*b*c"
   * 
   * @param a Seite a, mit Wert >= 0
   * @param b Seite b, mit Wert >= 0
   * @param c Seite c, mit Wert >= 0
   * @return Volumen nach der Formel "V = a * b * c"
   * @exception InvalidParameterException Wenn a oder b oder c < 0
   */
  public double computeCuboidVolume(double a, double b, double c) throws InvalidParameterException

• Besonderheiten bei Parameter (Verhalten bei Übergabe von "Null") sind beschrieben.
• Aussehen der Rückgabe ist beschrieben.
• Exceptions gibt es diesmal nicht.

  /**Abrufen der Zutatenliste. 
   * 
   * Beim Entfernen einer Zutat aus dem Kuchen werden die verbundenen Zutaten NICHT gelöscht !
   * Beim Laden des Kuchen werden sie NICHT mitgeladen. Ein Verwender kann die Zutatenliste eines aus der DB geladenen Kuchen also
   * nur abrufen, solange die Bean unter Entity-Manager-Kontrolle ist.
   *  
   * @return Liste der Zutaten.
   */
  @ManyToMany(mappedBy="kuchen", cascade={CascadeType.MERGE, CascadeType.PERSIST, CascadeType.REFRESH}, fetch=FetchType.LAZY)
  public Collection<ZutatNMBean> getZutaten()
  {
    return this.collZutaten;
  }

  /**Abrufen der Zutatenliste. 
   * 
   * Beim Entfernen einer Zutat aus dem Kuchen werden die verbundenen Zutaten NICHT gelöscht !
   * Beim Laden des Kuchen werden sie NICHT mitgeladen. Ein Verwender kann die Zutatenliste eines aus der DB geladenen Kuchen also
   * nur abrufen, solange die Bean unter Entity-Manager-Kontrolle ist.
   *  
   * @return Liste der Zutaten.
   * @see ZutatNMBean#getKuchen()
   */
  @ManyToMany(mappedBy="kuchen", cascade={CascadeType.MERGE, CascadeType.PERSIST, CascadeType.REFRESH}, fetch=FetchType.LAZY)
  public Collection<ZutatNMBean> getZutaten()
  {
    return this.collZutaten;
  }

            /// <summary>
            /// Setzt und liefert den Primaer-Intervall
            /// </summary>
            public DateTimeNullableVonBis PrimaerIntervall
            {
                  get
                  {
                        return this.intervallPrimaer;
                  }
                  set
                  {
                        this.intervallPrimaer = value;
                  }
            }

            /// <summary>
            /// Setzt und liefert den Sekundär-Intervall
            /// </summary>
            public DateTimeNullableVonBis SekundaerIntervall
            {
                  get
                  {
                        return this.intervallSekundaer;
                  }
                  set
                  {
                        this.intervallSekundaer = value;
                  }
            }

    /// <summary>
    /// Macht aus einer Farbe einen Grauton.
    /// </summary>
    /// <param name="farbe"></param>
    /// <returns></returns>
    private Color ProjeziereAufGrau(Color farbe)
    {
      int intGrau = (int) Math.Round( 255* Math.Sqrt(farbe.R* farbe.R + farbe.G*farbe.G + farbe.B * farbe.B) / (Math.Sqrt(3) * 255) ,0);
      Color graustufe = Color.FromArgb(intGrau, intGrau, intGrau);
	  return graustufe;
    }

  /**{@inheritDoc}
   */
  @Override
  public KuchenNMBean findKuchenById(Integer int_Id)
  {

  /**{@inheritDoc}
     Zusätzlicher Kommentar.
     @param int_Id {@inheritDoc} (und außerdem gilt für diesen Parameter auch: ...)
   */
  @Override
  public KuchenNMBean findKuchenById(Integer int_Id)
  {

• Einen Überblick über die Funktion geben.
• Besonderheiten bei der Verwendung erklären.
• Erlaubte und unzulässige Werte für Parameter erklären
• Die Rückgabewerte erklären
• Exceptions und deren Ursachen erklären
• Bussiness-Logik erklären (vor allem, falls die nicht mal aus dem Quellcode hervorgeht)
• Und vor allem: dem Verwender das Gefühl geben, dass nichts innerhalb der Methoden passiert, was nicht in den Kommentaren steckt.

JavaDoc erzeugen

Das Erzeugen von JavaDoc geschieht leider in Eclipse nicht manuell. Man wählt das Projekt aus, für das man JavaDocs erzeugen will, und ruft im Menü "File" -> "Export..." auf. Im Export-Dialog wählt man "Java" -> "Javadoc" aus:

Alternativ wäre auch Menü "Project" => "Generate Javadoc..." möglich und würde zum selben nächsten Schritt führen.

Im nächsten Schritt wählt man die Projekt aus, für die man generieren will. Ich empfehle hier, alle Teilprojekte der Enterprise-Application zu wählen, im Beispiel also EJB-, Web- und ApplicationClient-Projekt. Außerdem wird die Option "Create Javadoc for members with Visibility" auf "Protected" gesetzt. Als Zielpfad empfehle ich ein Unterverzeichnis außerhalb des Projekts. Grund: ansonsten explodiert unsere Fehlerliste, weil das generierte HTML ebenfalls validiert wird.

Im Feld "javadoc command" muss man eventuell erst den Pfad zu "javadoc.exe" eintragen, je nachdem ob man im Projekt eine JRE oder ein JDK verwendet.

In Schritt 3 können wir alles auf den Defaults lassen.
In Schritt 4 müssen wir die "JRE source compatibility" vom Default "1.3" auf "1.6" ändern, damit Annotations verarbeitet werden:


Falls wir eine Anwendungsüberblick-Datei erzeugt haben ("overview.html)", geben wir den Pfad zur HTML-Datei in Schritt 4 an (Screenshot ist noch aus einer veralteten Version der Dokumentation - der Dateiname "package-template.html" stammt aus einem Mißverständnis meinerseits!):


Die Ausgabe des Javadoc-Laufs erscheint auf einer Konsole, und hier sollten wir ein Auge auf Fehler oder Warnungen haben.

Kommentare innerhalb Methoden

  /**Die übergebene Zutat löschen.
   * 
   * @param intZutatId ID der zu löschenden Zutat.
   * @exception EntityNotFoundException Wenn Zutat nicht gefunden wurde.
   */
  public void deleteZutat (Integer intZutatId)
  {
    logger.info ("deleteZutat " + intZutatId);
	
    //Die Zutat im EntityManager laden.
    //Hier mit "getReference" arbeiten, damit eine böse EntityNotFoundException fliegt wenn Zutat nicht gefunden wird.
    ZutatNMBean zutat = this.entityManager.getReference(ZutatNMBean.class, intZutatId );
   
    //Jetzt wird es knifflig: wir müssen die Kuchen der Zutat holen,
    //und aus den Zutat-Collections der Kuchen die Zutat entfernen.
    //Grund scheint zu sein dass der EntityManager ansonsten noch die
    //Zutat im Kuchen hält und dabei in einen Fehlerzustand läuft.
    Collection<KuchenNMBean> listeKuchen = zutat.getKuchen();
    Iterator<KuchenNMBean> iteratorKuchen = listeKuchen.iterator();
    while (iteratorKuchen.hasNext() == true) 
    {
      //Zutat aus der Zutatenliste des Kuchens entfernen:
      KuchenNMBean kuchenMitZutat = iteratorKuchen.next();
      kuchenMitZutat.getZutaten().remove(zutat);
    }

    //Jetzt endlich dürfen wir die Zutat löschen.
    this.entityManager.remove(zutat);
  }

  /**Finden des Kuchens zur übergebenen ID.
   * 
   * @param int_Id ID des gesuchten Kuchens
   * @return Gefundener Kuchen oder null, wenn nicht gefunden (es gibt in diesem Fall keine Exception)!
   */
  public KuchenNMBean findKuchenById(Integer int_Id)
  {
    logger.info ("findKuchenById " + int_Id);
    
    //Den Kuchen im EntityManager laden.
    //Hier mit "find" arbeiten, da bei ungültiger ID "null" zurückkommen soll. 
    KuchenNMBean kuchen = this.entityManager.find(KuchenNMBean.class, int_Id);
    
    //Falls etwas gefunden wurde, dann die Relationship einlesen.
    if (kuchen != null)
    {
      //Da der FetchType der ManyToMany-Relation auf LAZY gesetzt ist müssen die Zutaten 
      //hier explizit abgerufen werden solange die KuchenNMBean noch nicht
      //detached ist. Später würde ansonsten ein Zugriff auf die Zutatenliste eine
      //Exception auslösen.
      Collection<ZutatNMBean> collZutaten = kuchen.getZutaten();
      //Wir müssen einen Zugriff auf die Collection selbst ausführen, Abrufen der Property alleine reicht nicht !
      logger.info ("Anzahl Zutaten: " + collZutaten.size());
    }
    else
    {
      logger.info ("Kuchen zur ID " + int_Id + " nicht gefunden !");
    }
    
    return kuchen;
  }  

    //regulärer Ausdruck für benutzerdefinierte Eingaben
    private Regex neuerReg = new Regex("\\$(?<Tag>[^\\[]*)\\[(?<Typ>[^\\]]*)\\]\\$");

    public override DateTime Von
    {
      get
      {
        ...
      }
      set
      {
        //Anpassen auf den NÄCHSTEN Montag:
        DateTime datMontag = DatumZeitFunktionen.GetMontag(value);
        // Korrektur JK 18.01.2007
        if (datMontag < value) datMontag = datMontag.AddDays(7);
        base.Von = datMontag;
      }

            if (PeMKBBDataGlobal.HasBenutzerRecht(AppBaseGUIGlobal.ApplicationBase, AppBaseGUIGlobal.ApplicationBase.Benutzer, RechtPeMKBB.Objekt_Termin_Zeiten_Bearbeiten))
            {
              //this.dtpIstBeginn.Enabled = true;
              //this.dtpIstEnde.Enabled = true;
              this.dtpBeginn.Enabled = true;
              this.dtpEnde.Enabled = true;
              this.pnlBeginnEndeSynch.ReadOnly = false;
            }