Exkurs:

Projekte dokumentieren

Arbeiten mehrere Leute an einem Projekt zusammen, kann das ganz schnell unübersichtlich werden. Da hat jemand zum Beispiel eine Klasse programmiert, die kryptische Parameter- oder Methodennamen verwendet, von denen niemand weiß, wozu sie da sind, und jemand der mit dieser Klasse weiterarbeiten will, versteht nur Bahnhof. Also muss der Programmierer zu Rate gezogen werden: Über ICQ meldet er sich nicht, sein Handy ist aus. Was tun? Sich in den Quelltext der Klasse einzulesen würde viel zu lange dauern. Das Projekt kommt also zum Stillstand.

Um solche katastrophalen Situationen zu vermeiden, sollte man seine Quelltexte ausführlich dokumentieren. BlueJ bringt eine recht nützliche Funktion mit sich, die es ermöglicht, die im Quelltext implementieren Kommentare, gleich in eine Dokumentation im HTML-Format umzuwandeln. Die wird ausgedruckt, und die Leute, die mit dem Quelltext weiterarbeiten wollen, sind glücklich.

Kommentare schreiben

Java kennt zwei Typen von Kommentaren: Einzeilige Kommentare werden mit // eingeleitet. Mehrzeilige Kommentare werden mit /* eingeleitet. Das Ende eines mehrzeiligen Kommentars wird durch */ beschrieben. Am Anfang jeder Zeile eines mehrzeiligen Kommentars muss ein * stehen.

Bei einem gut dokumentieren Projekt sollte jede Methode einen eigenen Kommentar haben, der erklärt, was die Methode macht, welche Parameter sie erwartet und was sie zurückliefert.
Eine genauere Beschreibung der Vorgänge innerhalb der Methode ist nicht notwendig. Es ist nicht nötig zu wissen, wie ein Algorithmus funktioniert, solange er funktioniert.

Hat man zum Beispiel eine etwas kompliziertere Methode wie die fiktive Funktion int potenziere(int basis, int exponent), so würde als Kommentar "Potenziere basis mit exponent" völlig ausreichen. Unangemessen wäre etwas wie "In dieser Funktion wird in einer for-Schleife, bei der die Zählvariable i bei jedem Schleifendurchlauf um 1 erhöht wird, bis sie größer oder gleich exponent ist, basis mit sich selbst multipliziert, solange, bis die for-Schleife abgelaufen ist."
Das Verständnis der Arbeitsweise ist zum Arbeiten mit einer Methode also nicht erforderlich.

Die Dokumentation erzeugen

BlueJ benötigt eine besondere Art des Kommentars, um die HTML-Dokumentation zu erzeugen. In unserem Beispielprojekt gibt es eine Klasse Mensch mit zwei Konstruktoren:

Über das Auswahlfenster oben rechts, kann man jetzt vom Implementations- in den Interface-Modus wechseln.

Im Interface-Modus wird eine HTML-Dokumentation in einem genormten Format erstellt. Diese Dokumentation sieht in etwa so aus:

Die vollständige Dokumentation finden Sie hier.

Das sieht zwar schon mal ganz nett aus, aber es fällt auf, dass weder eine der Funktionen, noch die Klasse selbst irgendwie kommentiert ist, wie es eigentlich gedacht war. Diese Dokumentation liefert zwar einen Überblick über die Klasse und ihre Methoden, aber genauere Beschreibungen der Methoden finden sich nicht.

Um BlueJ zu vermitteln, dass ein Kommentar in die Dokumentation übernommen werden soll, muss ein besonderer mehrzeiliger Kommentar verwendet werden. Dieser unterscheidet sich vom normalen mehrzeiligen Kommentar dadurch, dass er mit /** eingeleitet wird (und nicht mit /* ). Also ergänzen wir die Klasse Mensch um einige solcher Kommentare:

Hat man dies getan, sieht auch gleich die Dokumentation viel schöner aus:

Die vollständige Dokumentation finden Sie hier.

Bei der Erstellung der HTML-Dokumentation kann BlueJ bestimmte Anweisungen in den Kommentaren interpretieren. So erzeugt die Anweisung

@param Parametername Parameterbeschreibung

zum Beispiel eine Zeile einer Parametertabelle. Folgende Anweisungen werden interpretiert:

@param Parametername Parameterbeschreibung
@return Beschreibung des Rückgabewertes]
@version Versionsnummer (funktioniert nur in der Klassenbeschreibung)
@author Autor (funktioniert nur in der Klassenbeschreibung)

Da die Dokumentation in HTML verfasst ist, können Sie in Ihren Kommentaren auch gewöhnliche HTML-Tags unterbrigen. Das beinhaltet von einfachen <b>-Tags bis hin zu JavaScript (ob man das wirklich braucht, ist eine andere Frage).

Ergänzen wir unseren Quelltext also um einige weitere Anweisungen:

Diese Anweisungen sehen in der Dokumentation so aus:

Zurück zu Folge 6: Bruchrechnung

Diese HTML-Seite wurde erstellt von Martin Helmich am 27. Februar 2005 mit Dreamweaver MX.