Kapitel 2

Dr. Bernd Kokavecz

Dokumentation

Mit Hilfe des in der Literatur ausführlich behandelten und hier kurz angerissenen Modellierungsverfahrens UML können OOA, OOD und OOP gut dokumentiert und auch grafisch dargestellt werden. Diese Dokumentationsmethode sollte auch in der Schule Verwendung finden. Von Schülern angefertigte Module (eine Datei mit mehreren zusammengehörenden Klassen) und auch einzeln gespeicherte Klassen müssen aber für das arbeitsteilige Vorgehen im Projektunterricht möglichst auch im Quelltext kommentiert werden.

Von Java kennen wir das Java-doc-System, das bestimmte Kommentare (/**) aus dem Quelltext herausfiltert und in eine HTML-Dokumentation umwandelt. Als Lehrer kann man hier gut erkennen, ob alle geplanten Klassen und Methoden auch im Quelltext ausführlich kommentiert sind und ob diese Beschreibungen mit dem Entwurf übereinstimmen.

Auch für Python gibt es im Internet ein Werkzeug mit ähnlichem Ansatz, das sich aber zur Zeit noch in einem sehr frühen Entwicklungsstadium befindet (auch ein GUI-Builder ist bereits in Arbeit)

Unabhängig davon unterstützt Python zwei Kommentierungsverfahren:

  1. Steht in einer Zeile das Zeichen # , so werden alle Zeichen bis zum Zeilenende als Kommentar betrachtet.
  2. Steht in der Zeile nach "class" oder "def ...." statt einer Anweisung ein String, so wird dieser String als "DocString" (ähnlich Javas /**) verstanden. Mit dem Module docstr lassen sich diese Kommentare auch programmiertechnisch auswerten. Das mir vorliegende Pythonsystem besitzt allerdings das Module docstr nicht, die Syntax aber wird akzeptiert.

Hinweis: Strings können in Python mit "das is n string" oder 'das ooch' gekennzeichnet werden, wodurch die entsprechenden Zeichen auch Bestandteil einer Zeichenkette werden können: ("Watt'n datte da" oder 'Sag "DU" zu mir').
ACHTUNG!  Leitet man eine Zeichenkette mit DREI Anführungszeichen ein und aus (z.B. mit """), so darf der String (incl. Zeilenwechsel) sich über mehrere Zeilen erstrecken!

Um im Unterricht eine gewisse Einheitlichkeit im Programmierstil und in den Dokumentationsmethoden zu erlangen, habe ich einige Regeln für meine Schülerinnen und Schüler aufgestellt, die das Schreiben des Programmcodes und das Dokumentieren betreffen. Zusätzlich habe ich ein kleines Script geschrieben, das es erlaubt, die Dokumentation (in bescheidenem Umfang) aus dem Quelltext zu extrahieren, wobei die verwendete Methode kompatibel ist zu pythons "docstr". Das verwendete Script ist allerdings nur unter Unix (Linux) verwendbar. (Linux auf den Desktop!)

Lesen Sie: Regeln für die Erstellung des Programmcodes und Beschreibung von pmdoc (python-mini-doc)

python zurück zur Startseite

Dr. Bernd Kokavecz
Datum: 25.04.2000
dr.bernd@kokavecz.de