13.3 Docstrings 

In Abschnitt 5.3, »Kommentare«, wurde der sogenannte Blockkommentar eingeführt. Ein Blockkommentar wird folgendermaßen geschrieben:

""" 
Dies ist ein Blockkommentar. 
Er kann mehrere Zeilen umfassen. 
"""

Der Name Blockkommentar wird den Möglichkeiten, die diese Notation bietet, jedoch nicht ganz gerecht. In der Python-Terminologie wird ein in drei doppelte oder einfache Hochkommata eingefasster Text Docstring genannt, kurz für »Documentation String«.

Docstrings sind dazu gedacht, Funktionen, Module oder Klassen zu beschreiben. Diese Beschreibungen können durch externe Tools oder beispielsweise die Built-in Function help gelesen und wiedergegeben werden. Auf diese Weise lassen sich sehr 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örper 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(object): 
    """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 folgendermaßen der Docstring des Moduls math der Standardbibliothek ausgelesen werden:

>>> import math 
>>> math.__doc__ 
'This module is always available.  It provides access to the\nmathematical functions defined by the C standard.'

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.

Ihr Kommentar