DocStrings

DocStrings
	Kapitel 7. Funktionen

In Python gibt es eine sehr elegante Möglichkeit, Funktionen mit so genannten Dokumentations-Strings oder kurz DocStrings zu erläutern. DocStrings sind ein wichtiges Werkzeug, von dem Sie Gebrauch machen sollten, da sie dazu beitragen, das Programm zu dokumentieren und es besser verständlich zu machen. Bemerkenswert daran ist z.B., dass wir den DocString etwa einer Funktion sogar während des Programmablaufs abfragen können!

Verwendung von DocStrings

Beispiel 7.8. Verwendung von DocStrings (funk_doc.py)

				
#!/usr/bin/python

def printMax(x, y):
	"""Gib das Maximum von zwei Zahlen aus.

	Die beiden Werte muessen ganze Zahlen sein."""
	x = int(x) # Umwandlung in ganze Zahlen, falls moeglich
	y = int(y)

	if x > y:
		print x, 'ist das Maximum'
	else:
		print y, 'ist das Maximum'

printMax(3, 5)
print printMax.__doc__

Ausgabe

				
$ python funk_doc.py
5 ist das Maximum
Gib das Maximum von zwei Zahlen aus.

	Die beiden Werte muessen ganze Zahlen sein.

So funktioniert es

Ein String in der ersten logischen Zeile einer Funktion ist der DocString für diese Funktion. Beachten Sie, dass man DocStrings auch für Module und Klassen verwenden kann, die wir in den jeweiligen Kapiteln noch kennen lernen werden.

Als Konvention benutzt man für DocStrings einen mehrzeiligen String, wobei die erste Zeile mit einem Großbuchstaben beginnt und mit einem Punkt endet. Danach bleibt die zweite Zeile leer. Dann kommt ab der dritten Zeile eine ausführlichere Erläuterung. Es wird ausdrücklich empfohlen, dieser Konvention in allen DocStrings für alle nichttrivialen Funktionen zu folgen. Bei sehr einfachen Funktionen verwendet man einen einzeiligen String, aber dennoch die dreifachen Anführungszeichen. Weitere Einzelheiten dieser Konvention finden Sie in der Python-Dokumentation unter dem Stichwort PEP 257.

Wir erhalten den DocString der Funktion printMax über das mit der Funktion verbundene Attribut __doc__ (beachten Sie die doppelten Unterstriche). Behalten Sie im Kopf, dass in Python alles als ein Objekt behandelt wird, also auch Funktionen. Wir werden im Kapitel über Klassen mehr über Objekte lernen.

Wenn Sie die Hilfefunktion help() in Python benutzt haben, haben Sie bereits den Gebrauch von DocStrings gesehen! Sie macht nämlich nichts anderes, als das __doc__-Attribut der Funktion auszuwerten und es in benutzerfreundlicher Weise auszugeben. Sie können das an der obigen Funktion ausprobieren - fügen Sie dem Programm einfach die Zeile help(printMax) hinzu. Denken Sie daran, dass Sie die Hilfefunktion mit der Taste q beenden.

Automatisierte Werkzeuge können so die Dokumentation Ihres Programms abrufen. Deshalb möchte ich Ihnen ausdrücklich empfehlen, allen nichttrivialen Funktionen DocStrings hinzuzufügen. Der Befehl pydoc, der mit zur Python-Distribution gehört, arbeitet ähnlich wie help() auf der Basis von DocStrings.


Die return-Anweisung		Zusammenfassung