Entwurfsentscheidung dokumentieren

Regel: Drücke im Klassenkommentar in einem Satz beginnende mit dem Klassennamen die wesentlichen Entwurfseinscheidung (Attribute und Beziehungen) und/oder die Verantwortung (abstrakte Beschreibung des Verhaltens der Objekte) aus.

Regel: Um das Geheimnisprinzip zu waren, vermeide möglichst jeden rein Implementierungstechnischen Bezug (z.B. Nennung von Datentypen).

Begründung: Zum besseren Verständis der Klasse

Beispiel

Nehmen wir an es existieren die Klassen Hochschule, Student, Dozent und Studiengang.

/**
  Eine Hochschule mit Studenten, Dozenten und Studiengängen.     
  */
public class Hochschule {

}

Der obige Kommentar drückt den Entwurf der Beziehungen von Hochschule zu anderen Klassen aus: die Klasse Hochschule hat jeweils eine 1-n Beziehung zu Student, Dozent und Studiengang.

/**
   Ein Student mit Namen, Matrikelnummer und seine 
   eingeschriebene Studiengänge.
  */
public class Student {
  private String name;
  private String matrikelnummer;
  private Studiengang studiengaenge [];
}

Dieser Kommentar nennt die wichtigsten Eigenschaften des Studenten und drückt eine 1-n Beziehung zum Studiengang aus.

Begründung

Um eine Klasse besser verstehen und verwenden zu können, muss deren Zweck mindestens grob beschrieben sein. Ansonsten muss jeder Entwickler sich aus den Detailinformationen (Methoden, Attribute) den Zweck der Klasse selbst zusammenreimen. Um die Klasse zu ändern, muss deren Zweck durch Nennung der wesentlichen Entwurfsentscheidungen klar abgegrenzt sein. Ansonsten ist die Gefahr groß, dass die Klasse so erweitert wird, dass sie die ursprünglichen Entwurfszielen nicht mehr erfüllt sind: normalerweise wird dadurch das Programm komplexer, schwerer zu verstehen und fehleranfälliger.

Nicht beschreiben, wo die Klasse verwendet wird

Regel: Beschreiben nie, wo (von welchen anderen Klassen) die Klasse verwendet wird.

Begründung: Es hilft normalerweise nicht, den Quelltext dadurch besser zu verstehen.

Begründung

Dies hilft normalerweise nicht zu verstehen, wofür die Objekte der Klasse verantwortlich sind und ist daher in einem Javadoc Kommentar meist nutzlos. Desweiteren bekommt man dadurch ungewollt Abhängigkeiten zwischen Klassen: Wenn die Klasse A die Klasse B verwendet, aber nicht umgekehrt, würde ein Kommentar in B mit Bezug zur Klasse A zu einer Abhängigkeit zu A führen. Je mehr Abhängigkeiten eine Klasse hat desto geringer ist die Wiederverwendung und desto schlechter die Wartbarkeit.