Programmierkurs Java Teil Objektorientierte Programmierung Unterrichtseinheit 36 Dokumentation

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ß Ø Dibos. Schach. Programm Ø Array. Index. Out. Of. Bounds. Exception Ø Attribute / Variablen: Ø Beginn mit Kleinbuchstaben; Anfangsbuchstaben weiterer Wortteile groß Ø anzahl. An. Zeichen Ø maximale. Groesse Ø Methoden: Ø Beginn mit Kleinbuchstaben; Anfangsbuchstaben weiterer Wortteile groß Ø get. Number Ø liefere. Naechsten. Spielzug Ø 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 javadoc. Schlü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 Hamster * erzeugt wird * @param spalte * die Spalte des Territoriums, in der Hamster * erzeugt wird * @param blickrichtung * die Richtung, in der Hamster anfangs schaut * (siehe Konstanten) * @param anzahl. Koerner * die Anzahl an Koernern, die der Hamster anfangs * im Maul hat * @throws Hamster. Initialisierungs. Exception * 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 anzahl. Koerner < 0 ist */ public Hamster(int reihe, int spalte, int blickrichtung, int anzahl. Koerner) throws Hamster. Initialisierungs. Exception {. . . } 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 Hamster. Nicht. Initialisiert. Exception * wird geworfen, wenn der Hamster noch nicht * initialisiert worden ist * @throws Mauer. Da. Exception * wird geworfen, wenn die Kachel in Blickrichtung * vor dem Hamster durch eine Mauer blockiert ist * oder Hamster in Blickrichtung am Rand des * Territoriums steht */ public void vor() throws Hamster. Nicht. Initialisiert. Exception, Mauer. Da. Exception {. . . } 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 Hamster. Nicht. Initialisiert. Exception * wird geworfen, wenn der Hamster noch nicht * initialisiert worden ist */ public boolean vorn. Frei() throws Hamster. Nicht. Initialisiert. Exception {. . . } 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 Hamster. Nicht. Initialisiert. Exception * wird geworfen, wenn der Hamster noch nicht * initialisiert worden ist */ public String lies. Zeichenkette(String aufforderung) throws Hamster. Nicht. Initialisiert. Exception {. . . } 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 Negativer. Wert. Exception */ public Cardinal(int w) throws Negativer. Wert. Exception { if (w < 0) throw new Negativer. Wert. Exception(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 to. String() { 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 obj 1 * erstes Cardinal-Objekt (!= null) * @param obj 2 * zweites Cardinal-Objekt (!= null) * @return Summe der beiden Parameter-Objekte */ public static Cardinal add(Cardinal obj 1, Cardinal obj 2) { try { if (obj 1. wert + obj 2. wert >= 0) { return new Cardinal(obj 1. wert + obj 2. wert); } else { // Summe > Integer. MAX_VALUE return new Cardinal(obj 1. wert + obj 2. wert – Integer. MIN_VALUE); } } catch (Negativer. Wert. Exception 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 Div. Null. Exception */ public static Cardinal div(Cardinal divident, Cardinal divisor) throws Div. Null. Exception { if (divisor. wert == 0) throw new Div. Null. Exception(); try { return new Cardinal(divident. wert / divisor. wert); } catch (Negativer. Wert. Exception 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 eingabe 1 = IO. read. Int("Natuerliche Zahl: "); int eingabe 2 = IO. read. Int("Natuerliche Zahl: "); Cardinal nat 1 = new Cardinal(eingabe 1); Cardinal nat 2 = new Cardinal(eingabe 2); Cardinal nat 3 = Cardinal. div(nat 1, nat 2); IO. println("Divisor: " + nat 2); IO. println("Divident: " + nat 1); IO. println("Quotient = " + nat 3); } catch (Negativer. Wert. Exception exc) { IO. println("negativer Wert: " + exc. get. Wert()); } catch (Div. Null. Exception 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 Div. Null. Exception 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 Negativer. Wert. Exception 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 Negativer. Wert. Exception(int wert) { this. wert = wert; } /** * get-Methode zum Liefern des (negativen) Wertes * * @return aktueller Wert des Attributes "wert" */ public int get. Wert() { 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