Python 3 - Lernen und professionell anwenden

189

6.14

Hinweise zum Programmierstil

6.14.3 Kommentierte Parameter

Zu einer professionellen Dokumentation gehört, dass im Funktionskopf die einzelnen Para-

meter kommentiert werden. Das ist insbesondere dann sinnvoll, wenn Sie einzelne Buch-

staben oder Abkürzungen als Bezeichner verwenden. Sie schreiben die Parameter

untereinander in verschiedene physische Zeilen. Der Python-Interpreter sieht sie dann als

eine einzige logische Zeile an. In jedem Kommentar erklären Sie kurz die Bedeutung des

jeweiligen Parameters und geben – sofern das wichtig ist – den erwarteten Typ an. Beispiel:

6.14.4 Docstrings

Unterhalb des Funktionskopfes kann ein Kommentar in Form einer Zeichenkette eingefügt

werden. Dieser Docstring sollte in dreifachen Anführungszeichen stehen. Die erste Zeile

besteht aus einer knappen Beschreibung der Aufgabe der Funktion. Der Name der Funktion

braucht dabei nicht wiederholt zu werden. Die zweite Zeile bleibt leer. Die weiteren Zeilen

können Angaben zu folgenden Punkten enthalten:

쐽 Vorbedingungen: Welche Eigenschaften müssen die übergebenen Parameter besitzen,

damit die Funktion richtig arbeitet?

쐽 Nachbedingungen: Welche Objekte gibt die Funktion zurück und welche Eigenschaften

besitzen sie?

쐽 Welche globalen Variablen werden verwendet und welche Seiteneffekte werden verur-

sacht?

쐽 Name des Autors und Datum der letzten Änderung

Der Docstring einer Funktion kann im interaktiven Modus mit der

help()-Funktion zum

Vorschein gebracht werden. Beispiel:

def druckeEtikett( name, # chemische Bezeichnung (String)

formel # chemische Formel (String)

r_saetze, # Tupel von Nummern

s_saetze, # Tupel von Nummern

gefahrenhinweis, # z.B. "aetzend" (String)

fuellmenge # Füllmenge in g

(Integer)

)

>>> def tueNichts():

""" DieseFunktion macht nichts.

Sie verwendet keine Parameter,

hat keine Seiteneffekte und

gibt nichts zurück.

M. Weigend 13.1.2013

"""

pass