Es ist schon schwierig Qualität von Software zu definieren und zu messen. Sicher gehört eine gute Dokumentation dazu. Wie nun aber die Qualität der Dokumentation bewertet werden könnte, darüber gibt es wahrscheinlich noch mehr Meinungen als zur Softwarequalität. Ob eine Dokumentation gut ist, hängt häufig auch von subjektiven Beurteilungen ab. Was dem einen zu knapp beschrieben ist, mag für den Experten schon überflüssig sein. Gerade beim Thema wie objekt-orientierte Entwürfe und Implementationen dokumentiert werden sollen scheiden sich die Geister. Wir wollen deshalb für die Bearbeitung dieses Postens auch kein Kriterium aufstellen. Tun Sie dies selber! Jetzt wo Sie Erfahrung mit Java haben, können Sie auch mitreden.
Mit javadoc werden automatisch aus dem Quellcode von Javaprogrammen Dokumentationen extrahiert. Dieses Vorgehen hat an und für sich schon einige Vorteile:
Ein Werkzeug ist aber noch lange nicht die Lösung eines Problemes, sondern eben nur ein Werkzeug zur Behebung des Problems. In unserem Fall heisst das, dass Sie mit javadoc eben nur eine HTML-Datei erzeugen lassen können. Deren Inhalt müssen Sie weiterhin selber schreiben! Die Qualtät des Layouts ist vorgegeben, die des Inhaltes bestimmen Sie. Es macht Sie auch niemand darauf aufmerksam, dass Ihr Code nicht richtig oder unvollständig kommentiert ist, oder dass die Kommentare veraltet sind.
Gerade letzte Aussage ist wichtig. Das Extrahieren von Dokumentation aus dem Quellcode erweckt häufig den Eindruck von Vollständigkeit und Akkuratesse. Dieser Eindruck kann aber trügerisch sein. Warum beharren wir so auf diesem Punkt? Sie werden beim Kommentieren Ihres Codes bemerken, dass Sie zum Teil vor lauter Kommentaren den eigentlichen Code nicht mehr sehen. Genau diese Unübersichtlichkeit verleitet dann dazu den Kommentar zu kürzen oder gar ganz wegzulassen. Wenn Sie nach Monaten Ihren Quellcode ändern, sollten Sie eben auch den Kommentar ändern und nebst der Kompilation des Programmtextes auch eine Extraktion des Kommentares vornehmen.
Java-Dokumentation - javadoc - Tips und Hinweise - Lösungsmöglichkeit
OOP - Werkzeuge - Referenzen - Fäden - Synchronisation - Applets - Dokumentation
Werkstatt - Bibliographie