Kommentare

"Don't comment bad code - rewrite it" - Brian W. Kernighan und P. J. Plaugher

Trotz dieser durchaus richtigen Bemerkung von zwei berühmten Informatikern (Kernighan hat beispielsweise die Sprache C erfunden) sind Kommentare eine wichtige Hilfe für das Verstehen von Quelltexten.

Fremde Entwickler können sich leichter in eine Klasse einlesen, wenn diese gut kommentiert ist. Aber auch man selbst profitiert von Kommentaren, beispielsweise wenn die Klasse, die man gerade verwendet, schon vor ein paar Jahren geschrieben wurde und man sich nicht mehr an die Funktion der einzelnen Methoden erinnern kann.

In Java gibt es drei verschiedene Typen von Kommentaren.

Einzeilige Kommentare

int anzahl = 5; // Zahl der Wiederholungen

Die einzeiligen Kommentare beginnen mit zwei direkt aufeinander folgenden Schrägstrichen //. Alles was rechts von diesen beiden Zeichen steht, gilt als Kommentar. Einzeilige Kommentare werden meistens für kurze Hinweise, zur Erläuterung von Variablen etc. benutzt.

Mehrzeilige Kommentare

Natürlich kann man auch mit mehreren einzeiligen Kommentaren einen mehrzeiligen Kommentar erzeugen, aber neben dieser "Hau-drauf"-Methode gibt es "echte" mehrzeilige Kommentare. Diese beginnen mit den beiden Zeichen /* und enden mit */.

*/ Die folgende Methode laesst den Kreis um genau
   50 Pixel nach rechts wandern. 
   Wenn man diese Distanz selbst bestimmen moechte
   verwendet man besser die Methode moveHorizontal(int distance)
*/
   public void moveRight()
   {
	   distance += 50;
	}

Mit mehrzeiligen Kommentaren kann man gut den Sinn und Zweck von Methoden erklären oder von besonders aufwendigen und/oder ungewöhnlichen Konstrukten innerhalb einer Methode.

Javadoc-Kommentare

Diese Art von Kommentaren beginnt mit /** und endet mit */. Javadoc-Kommentare dienen zur automatischen Dokumentation von Java-Quelltexten mit dem Tool javadoc. Schauen wir uns mal einen typischen Javadoc-Kommentar einer Klasse aus dem Shapes-Projekt von BlueJ an.

     /**
     * Erase a given shape's from the screen.
     * @param  referenceObject  the shape object to be erased 
     */
    public void erase(Object referenceObject)
    {
        objects.remove(referenceObject);   // just in case it was already there
        shapes.remove(referenceObject);
        redraw();
    }

Die Javadoc-Kommentare können spezielle Tags wie @param oder @return enthalten, die in der automatisch erzeugten Dokumentation dann die Parameter und die Rückgabewerte kennzeichnen.

Dieses Bild zeigt einen Ausschnitt aus der der generierten Dokumentation der Klasse Circle.

Kommentare und die Schnittstelle einer Methode

Die Schnittstelle einer Methode besteht nicht nur aus der Signatur mit dem Methodennamen, der Parameterliste und dem Rückgabewert, sondern kann auch durch Kommentare zusätzlich spezifiziert werden. Hier ein Beispiel:

   // Diese Methode führt eine binäre Suche nach der gesuchten Zahl durch

      public int contains(int[] zahlen, int suchzahl)
      {
          // Der Quelltext
		}

Die Methode contains() verlangt, dass vom Benutzer der Methode zwei Vorbedingungen eingehalten werden:

Erstens darf der Array zahlen nicht leer sein (also zahlen != null)

Zweitens muss der Array sortiert sein, weil sonst eine binäre Suche unmöglich ist.

Dass in dem Array eine binäre Suche durchgeführt wird, geht aus der Signatur der Methode nicht hervor, wohl aber aus dem einzeiligen Kommentar zu Beginn der Methode.

Clean Code: Kommentare

Aus dem Buch "Clean Code" von Robert Martin (2009) fasse ich einmal das Wichtigste zusammen. Im Kapitel 4 stellt Martin Regeln vor, die man beim Schreiben von Kommentaren beachten sollte.

Nach Martin sind Kommentare im Grunde völlig überflüssig - zumindest wenn man guten Code geschrieben hat, dessen Klassen, Methoden, Variablen und Parameter aussagekräftige Namen haben, die schon alles über ihren Sinn und Zweck offenbaren.

"The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration."

Wenn sie eine Methode oder einen Algorithmus kommentieren wollen, überlegen zu zunächst, ob sich die Aussage nicht direkt im Quellcode ausdrücken lässt. Hier mal ein extrem negatives Beispiel aus der Praxis:

public void tausche(int i, int j)
{
   int temp = zahlen[i];   // Der Wert dieses Arrayelements
                           // wird in der lokalen Variablen
                           // temp gespeichert.
   zahlen[i] = zahlen[j];  // Nun wird der Wert von zahlen[j]
                           // in das Arrayelement mit dem
                           // Index i geschrieben.
   zahlen[j] = temp;       // Schließlich wird der in temp 
                           // gespeicherte Wert in zahlen[j] 
                           // kopiert.}

Das Gleiche mit deutlich kürzerem Kommentar:

public void tausche(int i, int j)
// vertauscht die beiden an den Indices i und j 
// befindlichen Arrayelemente (Ringtauschprinzip)
{
   int temp  = zahlen[i];  
   zahlen[i] =  zahlen[j];  
   zahlen[j] = temp;}

Und nun versuchen wir einmal die Methode so zu formulieren, dass überhaupt kein Kommentar mehr benötigt wird.

public void vertauscheElementeAnIndices(int i, int j)
{
   int zwischenspeicher = zahlen[i];
   zahlen[i] =  zahlen[j];  
   zahlen[j] = temp;
}

Hier noch ein Beispiel direkt aus dem Buch von Martin:

// Check to see if the employee is eligible for full benefits
   if ((employee.flags & HOURLY_FLAGG) && 
       (employee.age > 65))
       ...

Und nun die bessere Version ohne Kommentar

   if (employee.isEligibleFurFullBenefits())
      ...

Der Trick ist hier, die drei Bedingungen der if-Anweisung in eine neue Methode mit einem aussagekräftigen Namen auszulagern. Auch der Java-Code wird dadurch kürzer und verständlicher.

Sinnvolle bzw. notwendige Kommentare

Notwendig sind Kommentare immer dann, wenn sie Autoren des Quelltextes, Versionsnummer und Erstellungsdatum enthalten. Oft werden solche Angaben sogar verbindlich vorgeschrieben ("Legal Comments").

Sinnvoll sind Kommentare auch dann, wenn Sie eine ungewöhnliche Entscheidung in ihrem Quelltext begründen wollen ("Explanation of Intent"). Warum haben Sie gerade diesen Algorithmus gewählt und nicht den "normalen", den andere Entwickler immer verwenden?

TODO-Kommentare

Wenn man an einem größeren Projekt arbeitet, ist es oft hilfreich, im Quelltext zu vermerken, an welchen Problemen man noch arbeiten muss bzw. welche Algorithmen noch verfeinert werden müssen. Das geschieht natürlich mit Hilfe von Kommentaren.