Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni

Transkript

1 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni Software-Dokumentation Nach einer Vorlesung von Prof. Andreas Zeller Lehrstuhl Softwaretechnik, Universität des Saarlandes, Saarbrücken. Übersicht: Warum Dokumentation? Kommentierter Code Literate Programming Javadoc 9.1 Warum Dokumentation? Besseres Verständnis, besseres Design: The designer of a new system must not only be the implementor and the first large-scale user; the designer should also write the first user manual. (... ) If I had not participated fully in all these activities, literally hundreds of improvements would never have been made, because I would never have thought of them or perceived why they were important (Donald Knuth zu dem Design von TEX) Die präzise Dokumentation eines Systems für andere zwingt zu einem anderen Blickwinkel: Weg von den internen Details Hin zu der dem Benutzer oder Programmierer bereitgestellten Funktionalität Arten der Dokumentation Design-Dokument Leser: Neue Programmierer Inhalt: Übersicht, Abstraktionen, High-Level Funktionalität, Design-Entscheidungen, Anwendungsbereiche, Einschränkungen Tutorial Leser: Neue Programmierer Inhalt: Typische und einfache Nutzung, Beispiele Referenz-Handbuch Leser: Programmierer Inhalt: Nutzung, Schnittstellen-Beschreibungen, genaue Semantik, Einschränkungen Gleiches für den Benutzer eines Systems

2 68 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni Anforderungen an Dokumentation Der Code ist die beste Dokumentation: per Definition akkurat und aktuell Semantik ist schwer zu extrahieren Dokumentation der Schnittstellen, nicht der Implementierung Dokumentation gehört in die Sprache: Code und Dokumentation laufen nicht auseinander Compiler und Laufzeitsystem können Konsistenz prüfen z.b. Vor- und Nachbedingungen, Invarianten Dokumentation muss formal sein ermöglicht Verifikation Ziele der Dokumentation Abstraktion von der formalen Beschreibung Schnelles Verständnis des Systems Hintergründe, Entwurf, typische Nutzung Zusammenfassung der Funktionalität Dokumentation der Schnittstellen Dokumentation der Absicht des Programmierers Details der Implementierung Wiederverwendung von Code durch Suche in der Dokumentation Kommentare Kommentare können das Lesen von Programmen erheblich erleichtern. Aber: Der Compiler kann nicht prüfen, ob der Kommentar Sinn macht ob sich der Kommentar auf das Programm bezieht ob der Kommentar auf dem neuesten Stand ist Schlechte Kommentare sind schlimmer als gar keine Kommentare! Wie man nicht kommentiert Grundregel: Kommentare knapp und präzise halten. Statt

3 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni ***************************************************** * Start of function S Q R T (= "square root") * * SQRT takes an argument: * * - double X: the number to be squared (must be >= 0) * * SQRT returns: * * - the square root of X * * (c) 2004 H. Becker, Ottweiler - all rights reserved * ******************************************************* besser // Return the square root of X double sqrt(double x) {... Statt n += 1; // Increment n by one a *= n; // Multiply a with n return a; // Return the value of a besser n += 1; a *= n; return a; Grundregel: Kann ich etwas im Programmcode ausdrücken, brauche ich keinen Kommentar. Statt int d; // Current number of daffodils d = num_d(); // Compute number of daffodils assert (d == 2); // We expect two daffodils besser int currentdaffodils = numberofdaffodils(); int expecteddaffodils = 2; assert currentdaffodils == expecteddaffodils; Wie man nicht kommentiert (4) Statt // Invariant: x > 0 and y > 0 besser assert x > 0 && y > 0; Wie man kommentiert Stroustrup (Author von C++) wünscht sich: Einen Kommentar für jede Quelldatei Einen Kommentar für jede Klasse

4 70 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007 Einen Kommentar für jede nichttrivale Funktion, der den Zweck der Funktion ausdrückt der ggf. die Vorgehensweise (= den Algorithmus) beschreibt Einen Kommentar für jede (globale) Variable und Konstante Kommentare für nicht-offensichtliche oder nicht-portable Stellen Very little else 9.2 Literate Programming Motivation: Idee: Eine Dokumentation muss mit dem Programm zusammen entstehen Das Programm ist ein Artefakt einer gute Dokumentation des Lösungsweges Schreibe die Dokumentation des Systems Bette Codefragmente so ein, dass sie extrahiert und zu einem Programm zusammengestellt werden können Erste Implementierung: WEB [Knuth] TeX und Pascal, Tools: Weave und Tangle Beispiel von Knuth (wc.w im Most \.{CWEB programs share a common structure. It files main We must include the standard I/O definitions, since want to send formatted output to stdout and files...@>= #include The status variable JavaDoc Umgekehrter Ansatz zum Literate Programming: Integriere Dokumentation in den Quellcode Javadoc wird benutzt, um HTML-Dokumentation für Java Packages und Klassen zu erstellen. Dazu werden die öffentlichen Klassen-, Interface- und Methodendeklarationen verarbeitet und mit zusätzlichen Informationen aus eventuell vorhandenen Dokumentationskommentaren versehen. Pro Klassen Datei foo.java wird eine HTML Datei foo.html erstellt und alle Dateien eines Pakets werden mit Querverweisen verlinkt. Es werden zusätzlich diverse Index- und Hilfsdateien produziert, die das Navigieren in den Dokumentationsdateien erleichtern. Doxygen leistet Ähnliches für C++.

5 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni Benutzung von JavaDoc Javadoc nimmt als Input ein Verzeichnis von Java Klassen und produziert als Output ein Verzeichnis von verlinkte und navigierbare HTML Dateien. Die Kommandozeilenbenutzung des Programmes sieht so aus: javadoc -d doc-dir -sourcepath src-dir, wobei doc-dir das Zielverzeichnis und src-dir das Quellverzeichnis ist. Benutzt man ein IDE, so ist Javadoc in der Regel integriert: Bereits ohne zusätzliche Informationen erstellt Javadoc aus dem Quelltext eine recht brauchbare Beschreibung aller Klassen und Interfaces. Die Ausgabe wird durch Einfügen von Dokumentationskommentaren vervollständigt. Ein Dokumentationskommentar wird mit und endet mit umschlossen. Er wird im Quelltext unmittelbar vor dem zu dokumentierenden Item plaziert (einer Klassendefinition, einer Methode oder einer Instanzvariable). Er kann aus mehreren Zeilen bestehen. Die erste Zeile wird als Kurzbeschreibung verwendet. Innerhalb der Dokumentationskommentare dürfen bestimmte HTML-Tags vorkommen, um die Formatierung der späteren Dokumentation vorzugeben. Die Dokumentationskommentare sind in Abschnitte gegliedert, die durch Tags gekennzeichnet werden. Jeder Tag steht am Anfang der Zeile und beginnt mit dem Beispiel package games; import java.util.map; * A simple flower game Daniel Huson public class Game { int numberoftypesofflowers; Map<String,Integer> flowervalues; check class invariants public void check () { assert numberoftypesofflowers>1;

6 72 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007 assert numberoftypesofflowers==flowervalues.keyset().size(); * add a new flower type to the game typename currentcount public void addnewflowertype (String typename,int currentcount) { // add flower type here Dokumentationsseite: Wichtigste Tags Diese Tags werden in dem Dokumentationskommentar einer Klasse oder eines Interfaces name version JDK-Version Seit wann existiert diese reference Querverweis auf eine andere Klasse, Methode oder Teil der Dokumentation Beispiel * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> *

7 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni Sami Shaio %I%, %G% java.awt.basewindow java.awt.button class Window extends BaseWindow {... Diese Tags werden in dem Dokumentationskommentar einer Methode name description Beschreibung eines Parameters einer description Beschreibung des Rückgabewerts einer classname description Beschreibung eines Exceptions, das von der Methode geworfen description Kennzeichnet eine veraltete Klasse oder Methode, die nicht mehr verwendet werden sollte Beispiel * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * index the index of the desired character. the desired character. StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. java.lang.character#charvalue() public char charat(int index) {... So sieht der Dokumentationskommentar einer Klassenvariable aus: * The X-coordinate of the component. * #getlocation() int x = ;

8 74 Software Engineering, SoSe 07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni Querverweise Benutzung im java.lang.string The String Character#MAX a href= spec.html Java Spec The Java Programming Language Erscheinungsform String The String class String String.equals(Object) String.equals(java.lang.Object) java.lang.object.wait(long) Character.MAX RADIX Java Spec The Java Programming Language 9.4 Zusammenfassung Wichtige Regeln des Kommentierens: Schlechte Kommentare sind schlimmer als gar keine Kommentare! Kommentare knapp und präzise halten. Kann ich etwas im Programmcode ausdrücken, brauche ich keinen Kommentar. Literate Programming extrahiert Quellcode aus der Dokumentation. Javadoc (Doxygen bei C++) extrahiert Dokumentation aus Quellcode und nutzt hierfür spezielle Kommentare.