Kommentierung

  /**
   * 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

• Aus der Dokumentation geht nicht hervor, dass es Einschränkungen für die Parameter a, b und c gibt. Gemäß Doku wären hier +5, 0 und -5 zulässig.
• Es wird nirgends erklärt wie das Volumen überhaupt ermittelt wird.
• Wann und wie die Exception ausgelöst wird, wird nirgends erklärt.

  /**
   * 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

  /**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);
  }

• Warum wird "entityManager.getReference" verwendet statt "find" ?
  Erklärung: um bei ungültigen IDs eine Exception
• b) Was macht die Schleife ? Der Kommentar beschreibt zusammenfassend, was die Schleife überhaupt macht. Er ist hier sehr detailliert und begründet, warum die folgende Aktion notwendig ist. In diesem Detailgrad sind Kommentare nicht mehr nötig, wenn man genügend Erfahrung im Umgang mit Relationships gesammelt hat und auf den ersten Blick sieht was zu tun ist.
  Aber gerade für einen EJB3-Neuling ist der Sinn dieser Schleife ohne detaillierten Kommentar nicht erkennbar.
  

  /**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;
  }  

    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;
      }

• Kommentare sollten immer Code-Blöcke zusammenfassen und damit die Lesbarkeit des Codes erhöhen.
• Sie sollen Besonderheiten und Workarounds erklären, und zwar so, dass man auch nach 5 Jahren noch weiß was man sich damals gedacht hat !
• Wenn man in bestehendem Code etwas ändert, dann macht es Sinn, einen Bekennerbrief und eine Begründung zu hinterlassen ;-).