Das Dokumentieren von Programmcode ist für viele eine lästige Angelegenheit. Jedoch ist es zum Einen für sich selber wichtig, den einen oder anderen Kommentar im Code zu hinterlassen, um sich nach etlichen Wochen wieder im eigenen Code zurecht zu finden, zum Anderen für Mitarbeiter oder Mitprogrammierer, die sich vielleicht in dem Code einarbeiten müssen, um ihn zu erweitern. Python bietet zur Dokumentation grundsätzlich zwei verschiedene Varianten: den einfachen Kommentar und den DocString mit den drei Anführungszeichen. In diesem Artikel hebe ich die Unterschiede der Kommentarmöglichkeiten in Python hervor, gehe etwas näher auf die DocStrings ein und nenne in diesem Rahmen einige automatischen Dokumentationsgeneratoren.
Besonders Anfänger, die gerade das Programmieren erlernen möchten, fällt es häufig schwer, ihr Programm ordentlich zu kommentieren und zu dokumentieren. Das ist grundsätzlich ja verständlich: Es muss eine Aufgabe womöglich aus dem Studium gelöst werden, es fehlt die Zeit und man ist voller Enthusiasmus bei der Sache. Dabei vergisst man leicht, dass jemand den Code eventuell kontrollieren muss und ihn dafür verstehen muss.
So ist es zumindest mir zu Beginn des Studiums gegangen.
Im Fach “Technische Mechanik” gab es Übungsblätter mit Aufgaben, die mit dem Computeralgebra-System Maple gelöst werden sollten. Ohne auf irgendeine Verständlichkeit des Maple-Programms zu achten, habe ich drauflos geschrieben. Bis der Tutor kam und mich alles mündlich erklären lassen hat. Mit der Zeit habe ich mir dann angewöhnt, Kommentare vor nahezu jeder neuen Zeile in Maple zu schreiben. Dadurch wurde es übersichtlicher und die Fehlersuche gestaltete sich ebenfalls einfacher.
Heutzutage bin ich ja dabei Python näher kennen zu lernen und habe mich daher informiert, welche Kommentarmöglichkeiten es in Python gibt, wie sie verwendet werden und wie aus denen ganze Dokumentationen erstellt werden können.
Zielgruppe der Kommentare
Zunächst ist es wichtig sich bewusst zu werden, dass es unterschiedliche Zielgruppen gibt, die verschiedene Anforderungen an die Kommentare in einem Programmcode haben. Grob können aus Sicht eines Programmierers zwei Gruppen unterschieden werden. Auf der einen Seite wären weitere Programmierer, die ein Programm verändern, anpassen oder erweitern wollen und auf der anderen Seite befinden sich die Anwender, welche es eigentlich nicht interessiert, wie ein Programm genau funktioniert, sie wollen lediglich die Verwendungssyntax wissen.
Bereits aus dieser einfachen Feststellung ergeben sich einige Bedingungen an die Kommentare, die man im Programmcode verteilt: Die Programmierer müssen den Code verstehen und hoffen daher auf möglichst detaillierte Kommentare an der dazu passenden Stelle. Für diesen Zweck eignen sich die ganz normalen Kommentare, wie sie in jeder Programmiersprache existieren. Dagegen schauen die Anwender eher ungern in fremden Code und wollen lediglich wissen, wie eine Funktion oder eine Klasse verwendet werden sollen. Hierfür schauen sie entweder in einer online Dokumentation oder Papierdokumentation nach. Möchte man dem Anwender das Leben etwas erleichtern, so fügt man in Python-Programmen die sogenannten DocStrings ein. Darin erklärt man dann, wie zum Beispiel die Funktion zu verwenden ist, welche Parameter erwartet werden und was sie ausgibt.
Zusammengefasst: Grundsätzlich gibt es zwei Zielgruppen:
- Programmierer
- Anwender
Python bietet mit den normalen Kommentaren und den DocStrings die richtige Antwort auf die Anforderungen der beiden Zielgruppen.
Kommentare für Programmierer
Natürlich sind die normalen Kommentare in Programmiersprachen nicht nur für Leuten vorbehalten, die irgendwann an dem Code etwas verändern sollen, die Erfahrung zeigt aber, dass Anwender in den seltensten Fällen sich für die genaue Implementierung interessieren.
Unter einem normalen Kommentar verstehe ich in Python das Rauten-Kommentar.
# importieren zusaetzlicher Module
import numpy as np
# Quadrieren einer komplexen Zahl
def quadriere(x):
# x: komplexe Zahl
# x.re: Realteil, x.im: Imaginaerteil
# Berechnung des realen Anteils:
real_= x.re*x.re-x.im*x.im
# imaginaerer Anteil
im_ = 2.0*x.im*x.re
x.re = real_
x.im = im_
# Ausgabe des Ergebnisses
return x;
# Das ist ein Kommentar
In dem Beispielcode habe ich munter Kommentare verteilt, ohne darauf zu achten, für welche Zielgruppe nun diese Funktion geschrieben wurde. Jeder Programmierer würde sich wahrscheinlich über derart kommentierte Funktionen freuen. Der Anwender findet die benötigten Informationen ebenfalls in den Kommentaren, jedoch muss er dafür erstmal in den Quellcode schauen.
Ich möchte hier nicht den Eindruck erwecken, dass die maximal mögliche Kommentaranzahl einher geht mit dem schnellstmöglichen und bestmöglichen Verständnisses des Quellcodes. Zu viele Kommentare können den Code unübersichtlich und schwer lesbar machen. Ein gesundes Gleichgewicht ist, wie fast überall, der goldene Weg.
Die gewöhnlichen #-Kommentare in Python sind, denke ich, allgemein verständlich und bekannt, weswegen ich nun zu den DocString-Kommentaren übergehen möchte.
Kommentare für Anwender
Jetzt wird es spezieller und interessanter. Wie ich bereits dargelegt habe, möchte der Anwender einer Funktion oder einer Klasse nicht unbedingt in den Quellcode schauen müssen und trotzdem die Nutzungssyntax erfahren. Dazu bieten sich die DocStrings an, welche sinnvoll hinter Klassen- oder Funktionenkopf geschrieben werden. Sie enthalten idealerweise alle notwendigen Informationen zur Benutzung der Klasse bzw. Funktion. Dazu zählen eine Aussage zum Zweck, ein Erläuterung der Übergabeparameter und eventuell eine Vorführung, wie die Funktion zu verwenden ist. Mit folgenden Fragen könnte ein Anwender an den Code haben:
- Wozu die Funktion/Klasse und was ist das Resultat?
- Was bedeuten die Parameter?
- Wie wird die Funktion aufgerufen?
An dieser Stelle könnte der Einwand aufgeführt werden, dass die DocStrings ja auch im Quellcode stehen und daher keinen Mehrwert zu den #-Kommentaren liefern. Wenn die DocStrings nur als Ersatz zu den #-Kommentaren im Quellcode verwendet werden, dann würde ich in meiner Unwissenheit diesem Einwand sogar zustimmen, jedoch sind die DocStrings zur Laufzeit verfügbar und können direkt in der Python-Shell aufgerufen werden:
print(quadriere.__doc__)
Ein derartiger Aufruf würde den DocString zur Funktion quadriere() liefern.
Somit ergeben sich folgende Vorteile für Anwender und Coder:
- Erklärung wie der Code verwendet werden soll, ohne den Quellcode lesen zu müssen.
- Reduktion der Aufruffrequenz der Dokumentation
- Automatische Generierung von Dokumentationen auf Basis der DocStrings
- Beispiele in DocStrings können zum Veranschaulichen und Testen verwendet werden.
So weit, so gut, kommen wir zu einem kleinen Beispiel:
# importieren zusaetzlicher Module
import numpy as np
# Quadrieren einer komplexen Zahl
def quadriere(x):
"""
Quadriert eine komplexe Zahl.
Argumente:
x: komplexe Zahl
x.re: Realteil, x.im: Imaginaerteil
"""
# Berechnung des realen Anteils:
real_= x.re*x.re-x.im*x.im
# imaginaerer Anteil
im_ = 2.0*x.im*x.re
x.re = real_
x.im = im_
# Ausgabe des Ergebnisses
return x;
# Das ist ein Kommentar
print(quadriere.__doc__)
Direkt im Anschluss an den Funktionskopf habe ich nun einen DocString platziert. Der Inhalt beschränkt sich auf die Erläuterung des Zwecks der Funktion quadriere() und die Klärung, was als Übergabeparameter erwartet wird. Die Ausgabe der print-Anweisung liefert den erwarteten DocString:
Quadriert eine komplexe Zahl.
Argumente:
x: komplexe Zahl
x.re: Realteil, x.im: Imaginaerteil
Konventionsgemäß habe ich den DocString in jeweils drei Anführungszeichen verpackt:""" ... """
Wie ich bereits dargelegt habe, ist es oft vorteilhaft, wenn man ein Verwendungsbeispiel in den DocString integriert. Diese Beispiele dienen zum Einen um dem Anwender klar zu machen, wie er die Funktion verwenden soll und was bei bestimmter Eingabe als Ausgabe zu erwarten ist. Zum Anderen können die Beispiele eine Testfunktion übernehmen. Sind die Beispiele korrekt geschrieben, so können sie mit dem Modul doctest ausgeführt werden. Gleichzeitig wird die Ausgabe, welche infolge der Testausführung zustande kam, mit der Soll-Ausgabe verglichen. Im Falle einer Abweichung wird eine Meldung herausgegeben.
Python-Programmierer, die IDLE als IDE verwenden, kommen mit DocStrings in den Genuss von zusätzlicher Hilfe beim Programmieren in Form von kleinen gelben Hilfefeldern, welche die erste Zeile eines DocStrings anzeigt, was das Programmieren sehr erleichtern kann. An dieser Stelle würde mich persönlich interessieren, ob auch andere IDE gibt, die ein derartiges Feature bieten. Vielleicht eine Emacs-Erweiterung?
So viel sei zu den #-Kommentaren und den DocStrings gesagt. Welche Vorteile bringen nun die DocStrings bei der Dokumentation des Python-Codes?
Automatische Generatoren von Dokumentationen
Möchte der Programmierer mehr Zeit für Interessanteres haben, als das Schreiben von Dokumentationen, so versieht er seinen Python-Code gleich mit DocStrings und lässt die Dokumentation von einem Generator automatisch erstellen. Bevor er jedoch anfängt zu programmieren kann es hilfreich sein, wenn er sich im Klaren ist, welchen Generator er verwenden möchte, denn einige benötigen eine besondere Auszeichnung des Textes in den DocStrings. Auf diese Weise erkennt der Generator, wie er welchen Text in der Dokumentation darstellen soll.
Folgende Tools helfen dem Programmierer Zeit zu sparen:
Die Liste ist nicht als erschöpfend zu verstehen, es gibt noch weitere Tools, die Dokumentationen aus Python-DocStrings verstellen können.
Ursprünglich wollte ich etwas näher auf EpyDoc eingehen, weil dies der Generator meiner Wahl ist, aber es würde den Rahmen des Artikels sprengen. Deswegen nenne ich an dieser Stelle erstmal die Gründe, warum ich mich für EpyDoc entschieden habe und schreibe in einem weiteren Artikel etwas zu dieser Software.
Der große Vorteil von EpyDoc, den ich für mich sehe, ist die Möglichkeit Latex-Dokumentationen erstellen zu können. Diese lassen sich dann ganz einfach als PDF-Dateien exportieren und man hat eine schöne Dokumentation, die gut ausgedruckt werden kann und anderen zur Verfügung gestellt werden kann. Der Export im HTML-Format ist für EpyDoc auch kein Problem. Die Dokumentation enthält dann mehrere Frames, welche die Navigation durch ein ständig angezeigtes Fenster erleichtern.
Ein Nachteil von EpyDoc ist sicherlich der zusätzliche Arbeitsaufwand bei der expliziten Auszeichnung des Textes innerhalb der DocStrings, was aber bei allen mir bekannten Generatoren nicht anders ist, außer PyDoc. Optimistisch betrachtet bietet die explizite Auszeichnung sogar Vorteile: Durch eine größere Vielfalt an unterschiedlichen Textauszeichnungsmöglichkeiten erhöht sich die Anzahl verschiedener Textgruppen und führt dadurch zu einer gesteigerten Übersichtlichkeit der Dokumentation.
Schlusswort
Insgesamt kann man überzeugend behaupten, dass die Verwendung von DocStrings aus mehreren und nicht nur gemeinnützigen Gründen sinnvoll ist. Zum Einen erleichtern sie die Verwendung des Codes durch andere Programmierer und zum Anderen ermöglichen sie die automatische Generierung von Dokumentationen.
Gründe genug, um den zusätzlichen Arbeitsaufwand beim Programmieren ohne zu Murren zu erledigen 
.
Nun möchte ich auch wissen, ob ihr die DocStrings einsetzt? Insbesondere interessiert mich dabei, ab welcher Projektgröße es für euch sinnvoll ist Dokumentationen mit dem DocStrings zu erstellen.
Artikel aus der selben Kategorie:
Meinungsfreiheit für alle!
Es gibt noch keine Kommentare zu “Python Dokumentation mit DocString”.
Jede Meinung ist willkommen!