Beschreibe was eine Methode macht

Regel: Beschreibe immer was die Methode macht, nicht wie sie implementiert ist.

Regel: Fange den Kommentar mit dem Verb des Methodennamens in Präsensform an.

Regel: Führe alle Parameter mit dem @param-Tag auf und beschreiben sie.

Regel: Beschreibe die Bedeutung des Rückgabewerts bei @return mit einer kurzen Phrase

Beispiel

public Hochschule {

  /**
   Immatrikuliert den student an dieser    
   Hochschule: ordnet dem Studenten eine Matrikelnummer zu
   und richtet ein Studienkonto für Studiengebühren und 
   Fachsemester ein. Die Matrikelnummer von student enthält
   danach eine neue Matrikelnummer.

   @param student der zu immatrikulierende student:
                  darf nicht null sein. Er darf noch
                  nicht an dieser Hochschule immatrikuliert
                  sein.
   */
  public immatrikulieren(Student student) {
  }

  /** 
   Gibt eine neue, eindeutige Matrikelnummer zurück.
   Sie ist eine fortlaufende 13-stellige Nummer mit
   führenden Nullen.

   @return eindeutige Matrikelnummer mit führenden Nullen
   */
  private String getNeueMatrikelnummer() {

  }   
}

Begründung

Um das Geheimnisprinzip zu wahren, sollten nicht Details der Implementierung einer Methode beschrieben werden, sondern nur was sie macht. Dieser Kommentar entspricht der detaillierten Spezifikation der Methode. Diese sollte vor der Implementierung vorhanden sein. Deswegen sollten Methoden besser schon kommentiert werden bevor man sie implementiert. Gelingt dies nicht, dann ist es sehr wahrscheinlich, dass man noch gar nicht genau weiss was die Methode machen soll geschweige denn wie man sie programmieren wird.