36    Dokumentation 

Wenn Sie Ihre Programme und Module an Benutzer und andere Entwickler weitergeben, ist eine gute Dokumentation sehr wichtig. Ohne vernünftige Funktionsbeschreibung ist selbst das beste Programm wertlos, da es zu aufwendig ist, die Funktionsweise allein aus dem Quellcode herauszulesen oder durch Ausprobieren zu erahnen.

Von Programmierern wird das Schreiben von Dokumentationen oft als lästig empfunden, weil es verhältnismäßig viel Zeit in Anspruch nimmt, ohne die Programme selbst zu verbessern. Aus diesem Grund gibt es auch in der Python-Welt viele Module und Programme, die nicht ausreichend dokumentiert sind.

Es gibt allerdings Werkzeuge und Methoden, die das Schreiben von Dokumentationen so einfach wie möglich machen. Wir werden uns in diesem Abschnitt mit dem Programm pydoc beschäftigen, das Python-Programme anhand ihres Quellcodes dokumentieren kann. Das Werkzeug pydoc analysiert den Programmtext und sammelt insbesondere die Informationen aus den sogenannten Docstrings. Die gesammelten Informationen werden aufbereitet und als HTML-Datei exportiert.

 

36.1    Docstrings 

Die Grundlage für die Hilfetexte, die von der dynamischen Hilfefunktion help angezeigt werden, sind spezielle Kommentare im Quelltext, auch Docstrings genannt (kurz für »Documentation String«). Docstrings sind dazu gedacht, Funktionen, Module oder Klassen zu beschreiben. Diese Beschreibungen können durch externe Tools oder die angesprochene Funktion help gelesen und wiedergegeben werden. Auf diese Weise lassen sich einfach Dokumentationen aus den – eigentlich programminternen – Kommentaren erzeugen.

Die folgenden beiden Beispiele zeigen eine Klasse und eine Funktion jeweils mit einem Docstring dokumentiert. Beachten Sie, dass ein Docstring immer am Anfang des Funktions- bzw. Klassenkörpers stehen muss, um als Docstring erkannt zu werden. Ein Docstring kann durchaus auch an anderen Stellen stehen, kann dann jedoch keiner Klasse oder Funktion zugeordnet werden und fungiert somit nur als Blockkommentar.

class MeineKlasse:
    """Beispiel fuer Docstrings.

    Diese Klasse zeigt, wie Docstrings verwendet
    werden. 
    """
    pass

def MeineFunktion(): 
    """Diese Funktion macht nichts. 

    Im Ernst, diese Funktion macht wirklich nichts.
    """
    pass

Um den Docstring programmintern verwenden zu können, besitzt jede Instanz ein Attribut namens __doc__, das ihren Docstring enthält. Beachten Sie, dass auch Funktionsobjekte und eingebundene Module Instanzen sind:

>>> print(MeineKlasse.__doc__)
Beispiel fuer Docstrings.

    Diese Klasse zeigt, wie Docstrings verwendet
    werden.
>>> print(MeineFunktion.__doc__)
Diese Funktion macht nichts. 
    Im Ernst, diese Funktion macht wirklich nichts.

Auch ein Modul kann durch einen Docstring kommentiert werden. Der Docstring eines Moduls muss zu Beginn der entsprechenden Programmdatei stehen und ist ebenfalls über das Attribut __doc__ erreichbar. Beispielsweise kann der Docstring des Moduls math der Standardbibliothek folgendermaßen ausgelesen werden:

>>> import math
>>> print(math.__doc__)
This module is always available.  It provides access to the
mathematical functions defined by the C standard.

Die eingebaute Funktion help erzeugt aus den in einem Objekt enthaltenen Docstrings eine Hilfeseite und zeigt diese im interaktiven Modus an:

>>> import math
>>> help(math) 

In Abbildung 36.1 sehen Sie die durch das oben dargestellte Beispiel erzeugte Hilfeseite.

Abbildung 36.1    Mittels help erzeugte Hilfeseite

Sobald Sie damit anfangen, größere Programme in Python zu realisieren, sollten Sie Funktionen, Methoden, Klassen und Module mit Docstrings versehen. Das hilft nicht nur beim Programmieren selbst, sondern auch beim späteren Erstellen einer Programmdokumentation, die zum Teil automatisch aus den vorhandenen Docstrings generiert werden kann.