Python - Docstrings

Hallo, aufstrebende Python-Programmierer! Heute tauchen wir in die wunderbare Welt der Docstrings ein. Als euer freundlicher Nachbar und Informatiklehrer freue ich mich, euch durch diesen wesentlichen Aspekt der Python-Programmierung zu führen. Also holt euch euer Lieblingsgetränk, macht euch komfortabel und lass uns gemeinsam auf diese Lernreise aufbrechen!

Docstrings in Python

Stell dir vor, du schreibst ein Tagebuch. Am Anfang jedes Eintrags notierst du vielleicht eine kurze Zusammenfassung dessen, was an dem Tag passiert ist. Docstrings in Python sind ein bisschen so! Sie sind besondere Zeichenketten, die beschreiben, was ein Codeabschnitt tut, und machen es für dich (und andere) einfacher, deinen Code später zu verstehen.

In Python sind Docstrings in dreifache Anführungszeichen (""" oder ''') eingefasst und werden direkt nach der Definition einer Funktion, Klasse oder eines Moduls platziert. Lass uns ein einfaches Beispiel anschauen:

def grüßen(name):
"""Diese Funktion grüßt die Person, die als Parameter übergeben wird"""
print(f"Hallo, {name}!")

In diesem Beispiel ist die Zeile zwischen den dreifachen Anführungszeichen unsere Docstring. Sie erklärt kurz, was die Funktion grüßen tut.

Einzeilige Docstrings

Für einfache Funktionen oder Klassen mag eine einzeilige Docstring alles sein, was du brauchst. Hier ist ein weiteres Beispiel:

def quadrieren(n):
"""Das Quadrat einer Zahl zurückgeben."""
return n ** 2

Diese Docstring ist kurz und knapp und sagt uns genau, was die Funktion tut, in nur einer Zeile.

Mehrzeilige Docstrings

Für komplexere Funktionen oder Klassen möchtest du vielleicht eine mehrzeilige Docstring benötigen. Diese enthalten typischerweise eine Zusammenfassungslinie, gefolgt von einer leeren Linie und dann detailliertere Informationen. Sieh dir ein Beispiel an:

def berechne_flaeche(laenge, breite):
"""
Die Fläche eines Rechtecks berechnen.

Parameter:
laenge (float): Die Länge des Rechtecks
breite (float): Die Breite des Rechtecks

Rückgabewert:
float: Die Fläche des Rechtecks
"""
return laenge * breite

Diese mehrzeilige Docstring bietet detaillierte Informationen über die Parameter der Funktion und was sie zurückgibt.

Docstrings für Module

Auch Module können Docstrings haben! Diese werden am Anfang der Datei platziert. Zum Beispiel:

"""
Dieses Modul enthält Dienstprogrammfunktionen für geometrische Berechnungen.
Es umfasst Funktionen zur Berechnung von Flächen und Volumina verschiedener Formen.
"""

def berechne_kreisflaeche(radius):
# Implementierung der Funktion hier

Docstrings für Klassen

Auch Klassen können Docstrings haben. Diese werden direkt nach der Klassendefinition platziert:

class Rechteck:
"""
Eine Klasse, die ein Rechteck darstellt.

Attribute:
laenge (float): Die Länge des Rechtecks
breite (float): Die Breite des Rechtecks
"""

def __init__(self, laenge, breite):
self.laenge = laenge
self.breite = breite

Zugriff auf Docstrings

Eine der coolen Dinge an Docstrings ist, dass du sie programmatisch zugreifen kannst. Python speichert die Docstring als das __doc__-Attribut der Funktion, Klasse oder des Moduls. So kannst du darauf zugreifen:

def grüßen(name):
"""Diese Funktion grüßt die Person, die als Parameter übergeben wird"""
print(f"Hallo, {name}!")

print(grüßen.__doc__)

Dies wird ausgeben: Diese Funktion grüßt die Person, die als Parameter übergeben wird

Best Practices für das Schreiben von Docstrings

Jetzt, da wir wissen, wie man Docstrings schreibt, sprechen wir über einige Best Practices:

1. Halte es prägnant, aber informativ
2. Verwende korrekte Grammatik und Interpunktion
3. Sei konsequent in deinem Stil
4. Füge Informationen über Parameter und Rückgabewerte für Funktionen hinzu
5. Beschreibe wichtige Attribute und Methoden für Klassen

Google Style Docstring

Google hat seine eigene Style-Richtlinie für Docstrings. Hier ist ein Beispiel:

def teile(a, b):
"""Zwei Zahlen teilen.

Args:
a (int): Der Zähler.
b (int): Der Nenner.

Returns:
float: Das Ergebnis der Division.

Raises:
ZeroDivisionError: Wenn b 0 ist.
"""
if b == 0:
raise ZeroDivisionError("Kann nicht durch null teilen")
return a / b

NumPy/SciPy Style Docstring

Wenn du mit wissenschaftlichen Python-Bibliotheken arbeitest, begegnest du vielleicht dem NumPy/SciPy Style:

def berechne_mittelwert(zahlen):
"""
Den arithmetischen Mittelwert einer Liste von Zahlen berechnen.

Parameters
----------
zahlen : list
Eine Liste von Zahlen.

Returns
-------
float
Der arithmetische Mittelwert der Eingabeliste.
"""
return sum(zahlen) / len(zahlen)

Sphinx Style Docstring

Sphinx ist ein beliebter Dokumentationsgenerator für Python. Sein Stil ist ähnlich dem reStructuredText-Format:

def fibonacci(n):
"""
Eine Fibonacci-Folge bis n generieren.

:param n: Die Anzahl der Fibonacci-Zahlen, die generiert werden sollen
:type n: int
:return: Eine Liste von Fibonacci-Zahlen
:rtype: list
"""
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence[:n]

Docstring vs Kommentar

Du fragst dich vielleicht, "Was ist der Unterschied zwischen einer Docstring und einem regulären Kommentar?" Große Frage! Lass uns das aufbrechen:

1. Syntax: Docstrings verwenden dreifache Anführungszeichen, während Kommentare # verwenden.
2. Platzierung: Docstrings kommen direkt nach einer Definition, während Kommentare überall stehen können.
3. Zweck: Docstrings erklären, was der Code tut, Kommentare erklären, wie er es tut.
4. Zugänglichkeit: Docstrings können programmatisch zugreifen werden, Kommentare nicht.

Hier ist ein kurzes Beispiel, um dies zu veranschaulichen:

def addieren(a, b):
"""
Zwei Zahlen addieren und das Ergebnis zurückgeben.
"""
# Dies ist ein Kommentar, der erklärt, wie wir die Addition durchführen
return a + b  # Dies ist ein inline-Kommentar

Und so ist es, Freunde! Wir haben die Ins und Outs der Python-Docstrings abgedeckt. Denke daran, gute Dokumentation ist wie das Hinterlassen von Brotkrümeln für dich (oder andere Entwickler) zu folgen. Es mag jetzt wie zusätzliche Arbeit sein, aber glaube mir, du wirst dich später bedanken!

Hier ist eine schnelle Referenztabelle der von uns behandelten Docstring-Stile:

Style	Zusammenfassung	Beispiel
Einzeilig	Kurze, einzeilige Beschreibung	"""Das Quadrat einer Zahl zurückgeben."""
Mehrzeilig	Detaillierte Beschreibung mit Parametern und Rückgabewert	"""Die Fläche eines Rechtecks berechnen.\n\nParameter:\n..."""
Google	Enthält Args, Returns und Raises Abschnitte	"""Zwei Zahlen teilen.\n\nArgs:\n..."""
NumPy/SciPy	Verwendet Parameters und Returns Abschnitte mit detaillierterer Formatierung	"""Den arithmetischen Mittelwert einer Liste von Zahlen berechnen.\n\nParameters\n----------\n..."""
Sphinx	Verwendet :param:, :type:, :return: und :rtype: Felder	"""Eine Fibonacci-Folge bis n generieren.\n\n:param n: ..."""

Happy coding, und möge dein Docstrings immer klar und informativ sein!

Credits: Image by storyset