Programmierkurs Java

Programmierkurs Java
Teil
Objektorientierte Programmierung
Unterrichtseinheit 36
Dokumentation
Dr. Dietrich Boles
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 1
Gliederung
 Programmdokumentation
 Dokumentation der Implementierung
 Java-Bezeichnerkonventionen
 Dokumentation des Protokolls / javadoc
 Beispiel ADT-Klasse Cardinal
 Zusammenfassung
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 2
Programmdokumentation
 2 Typen von Sourcecode-Dokumentation:
(1) Dokumentation des Protokolls
(2) Dokumentation der Implementierung
 Motivation für (1):
 Beschreibung der Funktionalität einer Klasse / Methode für andere
Programmierer
 Motivation für (2):
 bessere Verständlichkeit der gewählten Algorithmen
 einfachere Fehlersuche und Fehlerbeseitigung
 einfachere Wartung, Änderbarkeit und Erweiterbarkeit des Codes
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 3
Dokumentation der Implementierung (1)
 Dokumentation der Implementierung in Java:
 aussagekräftige Bezeichner (Klassen / Methoden / Variablen)
verwenden
 den Code gut strukturieren
 an "kritischen" Stellen Zeilenkommentare einbauen
 Java-Code-Konventionen!
Schlechtes Beispiel:
public class M {
public static int s(int x) {
int r = 0;
for(int i=1; i<=x; i++) { r = r + i; }
return r; } }
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 4
Dokumentation der Implementierung (2)
Gutes Beispiel:
public class Mathematik {
public static int summe(int bis) {
int ergebnis = 0;
// Zahlen von 1 bis "bis" addieren
for(int i=1; i<=bis; i++) {
ergebnis = ergebnis + i;
}
return ergebnis;
}
public static int fakultaet(int n) {
...
}
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 5
Java-Bezeichnerkonventionen
 Klassen:
 Anfangsbuchstaben jedes Wortteils groß
 DibosSchachProgramm
 ArrayIndexOutOfBoundsException
 Attribute / Variablen:
 Beginn mit Kleinbuchstaben; Anfangsbuchstaben weiterer Wortteile groß
 anzahlAnZeichen
 maximaleGroesse
 Methoden:
 Beginn mit Kleinbuchstaben; Anfangsbuchstaben weiterer Wortteile groß
 getNumber
 liefereNaechstenSpielzug
 Konstanten:
 ausschließlich Großbuchstaben; Trennung von Wortteilen durch
Unterstrich (_)
 MAX_VALUE
 INVALID_PARAM
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 6
Dokumentation des Protokolls / javadoc
 javadoc: Werkzeug des JDK zur Generierung von HTML-Code zur
Dokumentation des Protokolls einer oder mehrerer Klassen:
 Aufruf:
javadoc <.java-Datei(en)>
 Voraussetzung: Verwendung von javadoc-Kommentaren und javadocSchlüsselwörtern
 javadoc-Kommentare:
/** <zeichen> */
 javadoc-Schlüsselwörter:
 Beschreibung von Klassen:
Beschreibung der Funktionalität
@version <text>
@author <text>
 Beschreibung von Methoden:
Beschreibung der Funktionalität
Vorbedingungen, Nachbedingungen
@param <name> <beschreibung>
@return <beschreibung>
@throws <klassenname> <beschreibung>
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 7
Dokumentation des Protokolls / javadoc-Beispiel (1)
/**
* Repraesentation von objektorientierten Hamstern im
* Java-Hamster-Modell
*
* @author Dietrich Boles (Universitaet Oldenburg)
* @version 1.0 (25.01.2006)
*
*/
public class Hamster {
/**
* Blickrichtung Nord
*/
public final static int NORD = 0;
/**
* Blickrichtung Ost
*/
public final static int OST = 1;
/**
* Blickrichtung Sued
*/
public final static int SUED = 2;
/**
* Blickrichtung West
*/
public final static int WEST = 3;
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 8
Dokumentation des Protokolls / javadoc-Beispiel (2)
/**
* Konstruktor zum Erzeugen und Initialisieren eines Hamsters
* mit den uebergebenen Parametern
*
* @param reihe
*
die Reihe des Territoriums, in der der Hamster
*
erzeugt wird
* @param spalte
*
die Spalte des Territoriums, in der der Hamster
*
erzeugt wird
* @param blickrichtung
*
die Richtung, in der der Hamster anfangs schaut
*
(siehe Konstanten)
* @param anzahlKoerner
*
die Anzahl an Koernern, die der Hamster anfangs
*
im Maul hat
* @throws HamsterInitialisierungsException
*
wird geworfen, wenn: (a) eine Kachel
*
(reihe/spalte) nicht existiert
*
(b) die Kachel (reihe/spalte) durch eine Mauer
*
blockiert ist
*
(c) der Wert von blickrichtung nicht zwischen 0
*
und 3 liegt
*
(d) der Wert von anzahlKoerner < 0 ist
*/
public Hamster(int reihe, int spalte, int blickrichtung,
int anzahlKoerner)
throws HamsterInitialisierungsException { ... }
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 9
Dokumentation des Protokolls / javadoc-Beispiel (3)
/**
* Der aufgerufene Hamster springt auf die in Blickrichtung
* vor ihm liegende Kachel.
*
* @throws HamsterNichtInitialisiertException
*
wird geworfen, wenn der Hamster noch nicht
*
initialisiert worden ist
* @throws MauerDaException
*
wird geworfen, wenn die Kachel in Blickrichtung
*
vor dem Hamster durch eine Mauer blockiert ist
*
oder der Hamster in Blickrichtung am Rand des
*
Territoriums steht
*/
public void vor()
throws HamsterNichtInitialisiertException,
MauerDaException { ... }
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 10
Dokumentation des Protokolls / javadoc-Beispiel (4)
/**
* liefert genau dann true, wenn sich in Blickrichtung vor dem
* aufgerufenen Hamster keine Mauer befindet (wenn sich der
* Hamster in Blickrichtung am Rand des Territoriums befindet,
* wird false geliefert)
*
* @return true, wenn sich in Blickrichtung vor dem aufgerufenen
*
Hamster keine Mauer befindet; sonst false
* @throws HamsterNichtInitialisiertException
*
wird geworfen, wenn der Hamster noch nicht
*
initialisiert worden ist
*/
public boolean vornFrei()
throws HamsterNichtInitialisiertException {
...
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 11
Dokumentation des Protokolls / javadoc-Beispiel (5)
/**
* gibt den uebergebenen String auf den Bildschirm aus und
* fordert den Benutzer auf, einen String einzugeben; der
* eingegebene String wird als Wert geliefert
*
* @param aufforderung
*
der auszugebende String
* @return der vom Benutzer eingegebene String
* @throws HamsterNichtInitialisiertException
*
wird geworfen, wenn der Hamster noch nicht
*
initialisiert worden ist
*/
public String liesZeichenkette(String aufforderung)
throws HamsterNichtInitialisiertException {
...
}
...
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 12
Dokumentation des Protokolls / javadoc-Beispiel (6)
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 13
Beispiel ADT-Klasse Cardinal (1)
package number;
import io.IO;
/**
* ADT-Klasse zur Repraesentation Natuerlicher Zahlen als Objekte.
*
* @author Dietrich Boles
* @version 2.0, 06.03.2005
*/
public class Cardinal {
/**
* speichert den eigentlichen Wert
*/
protected int wert;
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 14
Beispiel ADT-Klasse Cardinal (2)
/**
* Default-Konstruktor; initialisiert mit dem Wert 0
*/
public Cardinal() {
this.wert = 0;
}
/**
* Konstruktor; initialisiert mit dem uebergebenen Wert
*
* @param w
*
Initial-Wert
* @throws NegativerWertException
*/
public Cardinal(int w) throws NegativerWertException {
if (w < 0)
throw new NegativerWertException(w);
this.wert = w;
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 15
Beispiel ADT-Klasse Cardinal (3)
/**
* Copy-Konstruktor; initialisiert mit einem existierenden Objekt
*
* @param obj
*
existierendes Cardinal-Objekt (!= null)
*/
public Cardinal(Cardinal obj) {
this.wert = obj.wert;
}
/**
* Klonieren eines Cardinal-Objektes
*
* @return kloniertes Cardinal-Objekt
*/
public Object clone() {
return new Cardinal(this);
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 16
Beispiel ADT-Klasse Cardinal (4)
/**
* String-Konvertierung
*
* @return Wert des Cardinal-Objektes als String-Repraesentation
*/
public String toString() {
return "" + this.wert;
}
/**
* Aufaddieren eines anderen Cardinal-Objektes
*
* @param obj
*
anderes Cardinal-Objekt (!= null)
*/
public void add(Cardinal obj) {
this.wert = Cardinal.add(this, obj).wert;
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 17
Beispiel ADT-Klasse Cardinal (5)
/**
* Addieren zweier Cardinal-Objekte
*
* @param obj1
*
erstes Cardinal-Objekt (!= null)
* @param obj2
*
zweites Cardinal-Objekt (!= null)
* @return Summe der beiden Parameter-Objekte
*/
public static Cardinal add(Cardinal obj1, Cardinal obj2) {
try {
if (obj1.wert + obj2.wert >= 0) {
return new Cardinal(obj1.wert + obj2.wert);
} else { // Summe > Integer.MAX_VALUE
return new Cardinal(obj1.wert + obj2.wert –
Integer.MIN_VALUE);
}
} catch (NegativerWertException exc) {
// kann nicht sein
return null;
}
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 18
Beispiel ADT-Klasse Cardinal (6)
/**
* Dividieren zweier Cardinal-Objekte
*
* @param divident
*
Divident als Cardinal-Objekt (!= null)
* @param divisor
*
Divisor als Cardinal-Objekt (!= null)
* @return Quotient der beiden Parameter-Objekte
* @throws DivNullException
*/
public static Cardinal div(Cardinal divident, Cardinal divisor)
throws DivNullException {
if (divisor.wert == 0)
throw new DivNullException();
try {
return new Cardinal(divident.wert / divisor.wert);
} catch (NegativerWertException exc) {
// kann nicht sein
return null;
}
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 19
Beispiel ADT-Klasse Cardinal (7)
// Testprogramm
public static void main(String[] args) {
try {
int eingabe1 = IO.readInt("Natuerliche Zahl: ");
int eingabe2 = IO.readInt("Natuerliche Zahl: ");
Cardinal nat1 = new Cardinal(eingabe1);
Cardinal nat2 = new Cardinal(eingabe2);
Cardinal nat3 = Cardinal.div(nat1, nat2);
IO.println("Divisor: " + nat2);
IO.println("Divident: " + nat1);
IO.println("Quotient = " + nat3);
} catch (NegativerWertException exc) {
IO.println("negativer Wert: " + exc.getWert());
} catch (DivNullException exc) {
IO.println("Division durch Null!");
}
}
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 20
Beispiel ADT-Klasse Cardinal (8)
package number;
/**
* Fehlerklasse fuer die Division durch 0
*
* @version 2.0, 06.03.2005
* @author Dietrich Boles
*/
public class DivNullException extends Exception {
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 21
Beispiel ADT-Klasse Cardinal (9)
package number;
/**
* Fehlerklasse fuer negative Zahlenwerte
*
* @version 2.0, 06.03.2005
* @author Dietrich Boles
*/
public class NegativerWertException extends Exception {
/**
* der fehlerhafte Wert
*/
protected int wert;
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 22
Beispiel ADT-Klasse Cardinal (10)
/**
* Konstruktor; initialisiert mit uebergebenem Wert
*
* @param wert
*
Initial-Wert
*/
public NegativerWertException(int wert) {
this.wert = wert;
}
/**
* get-Methode zum Liefern des (negativen) Wertes
*
* @return aktueller Wert des Attributes "wert"
*/
public int getWert() {
return this.wert;
}
Demo
}
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 23
Zusammenfassung
 Typen von Sourcecode-Dokumentation:
 Dokumentation des Protokolls ( javadoc)
 Dokumentation der Implementierung
 Sinn und Zweck:
 Nutzung von Klassen
 einfachere Fehlersuche und Fehlerbeseitigung
 einfachere Wartung, Änderbarkeit und Erweiterbarkeit des Codes
Programmierkurs Java
UE 36
Dokumentation
Dietrich Boles
Seite 24