Schneller und effizienter entwickeln – mit Javadoc

Hier ist ein vollständiges Javadoc-Projekt verfügbar, das als Beispiel für die Implementierung der Struktur verwendet werden kann. Zum Untersuchen des Projekts öffnet man einfach die Datei index.html.

Verwenden der Verzeichnisstruktur

Angenommen, man hat einen Algorithmus implementiert, der in einer Spezifikation gründlich beschrieben ist, und will diesen Code nun dokumentieren. Anstatt die Beschreibung des Algorithmus aus der Spezifikation abzuschreiben oder zu kopieren, ist es besser, einen Link zu der entsprechenden Stelle in der Spezifikation einzurichten. Dies beschleunigt die Dokumentation und – was noch wichtiger ist – dupliziert die Originalinformation nicht, so dass Code-Kommentare immer auf dem aktuellen Stand sind.

Ein Link von einer Quelldatei zu einer projektbezogenen Dokumentation im Verzeichnis /spec kann wie der folgende Code aussehen. Man sollte HTML und Javadoc-Synopsis zum Erstellen von Links verwenden. Ein Link kann auf Dokumente in unterschiedlichen Formaten verweisen, die mit dem Browser angezeigt werden können (Listing A).

Listing A

Diese Methode funktioniert sehr gut, wenn die projektbezogene Dokumentation zusammen mit dem Quellcode gespeichert und verteilt wird. In diesem Fall sind die Quellcode-Kommentare allerdings sehr eng mit bestimmten Dokumentennamen und Speicherorten verknüpft, so dass jede Änderung an diesen die Konsistenz des Kommentars zerstört.

Um das zu vermeiden, braucht man nur eine Zuordnung zwischen den Links aus dem Quellcode und bestimmten Dokumenten herzustellen. Dies kann man einfach mithilfe einer entsprechenden Datei erledigen. Die Datei spec.html enthält zum Beispiel die Zuordnungen zwischen den in Links verwendeten Namen innerhalb von Quelldateien und den echten Namen der referenzierten Dokumente. Ein Beispiel für einen Link von einer Quelldatei zu einem anderen Dokument mithilfe der Zuordnung in spec.html zeigt Listing B.

Listing B

Diese zusätzliche Ebene zur Trennung zwischen Namen und Speicherorten erlaubt das Ändern von Namen und Speicherorten der zugehörigen Dokumente, ohne zugleich den Quellcode ändern zu müssen, in dem die Verweise stehen.