9 Software-Dokumentation 9.1 Warum Dokumentation?

Software Engineering, SoSe’07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007
67
9 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
9.1.1
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
68
Software Engineering, SoSe’07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007
9.1.2
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
9.1.3
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
9.1.4
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!
9.1.5
Wie man nicht kommentiert
Grundregel: Kommentare knapp und präzise halten.
Statt
Software Engineering, SoSe’07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007
/*******************************************************
* 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;
9.1.6
Wie man kommentiert
Stroustrup (Author von C++) wünscht sich:
• Einen Kommentar für jede Quelldatei
• Einen Kommentar für jede Klasse
69
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:
• Eine Dokumentation muss mit dem Programm zusammen entstehen
• Das Programm ist ein Artefakt einer gute Dokumentation des Lösungsweges
Idee:
• 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 CWEB-System):
...
@ Most \.{CWEB} programs share a common structure.
It’s probably
...
@c
@<Header files to include@>@/
@<Functions@>@/
@<The main program@>
@ We must include the standard I/O definitions, since we
@ want to send formatted output to |stdout| and |stderr|.
@<Header files...@>=
#include <stdio.h>
@ The |status| variable ....
9.3
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++.
Software Engineering, SoSe’07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007
9.3.1
71
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 Zeichen “@”.
Beispiel
package games;
import java.util.Map;
/**
* A simple flower game
* @author Daniel Huson
* @date 6.2007
*/
public class Game {
int numberOfTypesOfFlowers;
Map<String,Integer> flowerValues;
/** check class invariants */
public void check () {
assert numberOfTypesOfFlowers>1;
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
* @param typeName
* @param currentCount
*/
public void addNewFlowerType (String typeName,int currentCount)
{
// add flower type here
}
}
Dokumentationsseite:
9.3.2
Wichtigste Tags
Diese Tags werden in dem Dokumentationskommentar einer Klasse oder eines Interfaces benutzt:
• @author name – Autorenname
• @version version – Versionsnummer
• @since JDK-Version – Seit wann existiert diese Klasse?
• @see 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>
*
Software Engineering, SoSe’07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007
73
* @author Sami Shaio
* @version %I%, %G%
* @see
java.awt.BaseWindow
* @see
java.awt.Button
*/
class Window extends BaseWindow {
...
}
Diese Tags werden in dem Dokumentationskommentar einer Methode benutzt:
• @param name description – Beschreibung eines Parameters einer Methode
• @return description – Beschreibung des Rückgabewerts einer Methode
• @exception classname description – Beschreibung eines Exceptions, das von der Methode geworfen wird
• @deprecated 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>.
*
* @param
index the index of the desired character.
* @return
the desired character.
* @exception StringIndexOutOfRangeException
*
if the index is not in the range <code>0</code>
*
to <code>length()-1</code>.
* @see
java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}
So sieht der Dokumentationskommentar einer Klassenvariable aus:
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
74
Software Engineering, SoSe’07, WSI, D. Huson, (Original Author: A. Zeller), 12. Juni 2007
9.3.3
Querverweise mit @see
Benutzung von @see im Quellkode
Erscheinungsform
@see
@see
@see
@see
@see
@see
@see
@see
@see
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
java.lang.String
java.lang.String The String class
String
String#equals(Object)
String#equals
java.lang.Object#wait(long)
Character#MAX RADIX
ha href=”spec.html”iJava Spechai
”The Java Programming Language”
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.