Kapitel III - Eine Schildkröte zum Zeichnen

Additum: Dokumentation der Klasse "Turtle"

Wir haben uns im Rahmen der bisher programmierten Programme immer mit einem entsprechenden Kommentar beschäftigt und auf diese Weise unsere Arbeit dokumentiert. Erst mal dient die entsprechende Dokumentation uns selbst. Sie hilft uns, später wieder auf leichte Weise mit dem Programm vertraut zu werden und damalige Gedanken wieder aufgreifen bzw. verstehen zu können.

Ebenfalls können Kommentare eine Hilfe sein, das Programm vorzustrukturieren oder einzelne Teile abzugrenzen. Beispiel:

# Vorbereitungen (importe etc.)
from turtle import Turtle
myTurtle = Turtle("turtle")
# eigentliches Programm
# hier stehen spaeter die entsprechenden Bewegungen der Turtle-Objekte
# Fenster geoeffnet lassen - fuer Linux
myTurtle.screen._root.mainloop()

Den letzten Kommentar können wir dann in einem zweiten Schritt durch die konkreten Anweisungen für die einzelnen Objekte ersetzen. Es bietet sich aber an, diesen ggf. leicht verändert beizubehalten, um den Quelltext und die Gedankengänge verständlicher zu machen.

In einem weiteren Schritt helfen unsere Kommentare bzw. die gesamte Dokumentation des Programmes einem fremden Leser oder Programmierer, das Programm bzw. die dahintersteckende Logik und Gedanken zu verstehen. Entsprechend einfach fällt einem dann die Erweiterung oder ggf. notwendige Korrektur des Programmes. Weiter stellt dies auch eine Hilfe für den Lehrer bei der Korrektur der Kursarbeit dar.

Die von einer Programmiersprache bereitgestellten Klassen, hier die Klasse Turtle, besitzen meist eine entsprechende Dokumentation. Diese soll den Nutzern der Klasse helfen und über Methoden und Attribute der einzelnen Objekte informieren.

Einerseits finden sich die entsprechenden Dokumentationen im Quelltext. Oftmals gibt es aber noch zusätzliche Orte, wo man die entsprechenden Informationen nachlesen kann. Meist sind dies Internetseiten oder Bücher. Insbesondere ist die Art der Dokumentation notwendig, wenn der Quelltext nicht ohne weiteres veröffentlicht werden soll und beispielsweise nur käuflich zu erwerben ist oder unter Umständen erst gar nicht veröffentlicht werden darf.

Auch für die Klasse Turtle gibt es eine entsprechende Internetseite, auf der die Attribute und Methoden vorgestellt und erläutert werden. Oftmals findet man dort auch weitere Erklärungen zu der Klasse oder ganze Beispiele. Die entsprechende Internetseite findest du unter http://docs.python.org/library/turtle.html.

Dort sind die einzelnen Methoden etc. aufgelistet. Wenn du auf diese klickst, wirst du zu einer genaueren Beschreibung meist mit Beispiel weitergeleitet. Meist lässt sich aber schon anhand des Namens ein grober Zweck ableiten. Entsprechend hier nochmal der Hinweis, möglichst prägnante Bezeichnungen für deine Variablen etc. zu wählen. Das erspart dir und anderen einiges an Raterei und Sucherei.

Die verlinkte Seite ist auf Englisch, wie viele Bücher bzw. Internetseiten in Zusammenhang mit der Programmierung oder Dokumentation von Klassen. Das liegt ganz einfach daran, dass sehr viele Leute Englisch sprechen und die entsprechenden Ausführungen verstehen können.

Wenn du Probleme beim Verständnis hast, nutze einfach ein im Internet verfügbares Wörterbuch, beispielsweise leo.org. Entsprechende Wörter kannst du einfach in die dort verfügbare Eingabemaske kopieren und so leicht übersetzen.