Teil 14: Python-Kommentare, Docstrings und Best Practices

In Python ist lesbarer, gut dokumentierter Code entscheidend – besonders in Data Science, wo Teams häufig zusammenarbeiten und große Projekte betreuen. Kommentare und Docstrings helfen, den Code klar zu strukturieren und verständlich zu machen. Außerdem zeigen wir Best Practices, um sauberen, wartbaren und effizienten Python-Code zu schreiben.

---

1. Kommentare in Python

Kommentare sind Text im Code, der nicht ausgeführt wird, sondern für Menschen gedacht ist.

Einzeilige Kommentare

# Dies ist ein einzeiliger Kommentar
x = 10  # Wert 10 zuweisen

• Beginnt mit #
• Ideal, um kurze Hinweise oder Erklärungen zu geben

Mehrzeilige Kommentare

"""
Dies ist ein mehrzeiliger Kommentar.
Kann über mehrere Zeilen gehen.
Wird oft für Beschreibungen verwendet.
"""

• Mehrzeilige Strings (""" """) können als Docstrings oder Blockkommentare genutzt werden

---

2. Docstrings: Dokumentation von Funktionen

Ein Docstring beschreibt was eine Funktion, Klasse oder ein Modul macht. Python-Tools wie help() nutzen Docstrings automatisch.

def addiere(a, b):
    """
    Addiert zwei Zahlen und gibt das Ergebnis zurück.

    Parameter:
    a (int oder float): Erste Zahl
    b (int oder float): Zweite Zahl

    Rückgabe:
    int oder float: Summe von a und b
    """
    return a + b

help(addiere)

• Ausgabe von help(addiere) zeigt den Docstring
• Docstrings sollten klar, prägnant und vollständig sein

---

3. Docstrings für Klassen

Auch Klassen und Methoden sollten dokumentiert werden:

class Kunde:
    """
    Repräsentiert einen Kunden mit Name und Alter.

    Attribute:
    name (str): Name des Kunden
    alter (int): Alter des Kunden
    """

    def __init__(self, name, alter):
        self.name = name
        self.alter = alter

    def begruessung(self):
        """
        Gibt eine Begrüßung für den Kunden aus.
        """
        print(f"Hallo {self.name}!")

• Docstrings für Klassen erklären Attribute und Methoden
• Praktisch für Teamarbeit und große Projekte

---

4. Inline-Kommentare vs. Block-Kommentare

Inline-Kommentare

x = 10  # Initialwert setzen

• Kurz, direkt neben dem Code
• Nicht überladen – nur wenn nötig

Block-Kommentare

# Berechnung der Umsatzsteuer
# Multipliziert Preis mit 0.19
umsatzsteuer = preis * 0.19

• Für längere Erklärungen oder komplexen Code

---

5. Best Practices für Kommentare

1. Kommentar den Code erklären, nicht wiederholen x = 10 # Setze x auf 10 (nicht sehr hilfreich)
2. Kurz, prägnant, verständlich
3. Aktualisieren – Kommentare müssen mit Code übereinstimmen
4. Keine redundanten Kommentare – klarer Code braucht weniger Kommentare

---

6. Code-Stil und Best Practices

Python folgt dem PEP8-Standard – Regeln für Lesbarkeit und Stil.

Beispiele

# Variablen
kunde_name = "Anna"  # klarer Name

# Funktionen
def berechne_umsatz(preis, anzahl):
    """Berechnet den Umsatz aus Preis und Anzahl"""
    return preis * anzahl

# Klassen
class Produkt:
    """Repräsentiert ein Produkt"""
    def __init__(self, name, preis):
        self.name = name
        self.preis = preis

Weitere PEP8-Empfehlungen

• 4 Leerzeichen für Einrückung
• Max. 79 Zeichen pro Zeile
• Leerzeilen zwischen Funktionen und Klassen
• Keine unnötigen Leerzeichen

---

7. Docstrings für Module

Module sollten ganz oben eine Beschreibung enthalten:

"""
modul_mit_funktionen.py

Dieses Modul enthält Funktionen für Data Science:
- addiere
- multipliziere
- berechne_umsatz
"""

• Hilft bei Dokumentation und automatisierten Reports

---

8. Praxisbeispiel: Vollständig dokumentiertes Data-Science-Modul

"""
daten_tools.py

Dieses Modul enthält Funktionen zur Datenanalyse:
- daten_laden
- berechne_durchschnitt
- filtere_vip
"""

import pandas as pd

def daten_laden(datei):
    """
    Lädt eine CSV-Datei in einen Pandas DataFrame.

    Parameter:
    datei (str): Pfad zur CSV-Datei

    Rückgabe:
    pd.DataFrame: Geladene Daten
    """
    try:
        df = pd.read_csv(datei)
        return df
    except FileNotFoundError:
        print("Datei nicht gefunden!")
        return None

def berechne_durchschnitt(df, spalte):
    """
    Berechnet den Durchschnitt einer Spalte.

    Parameter:
    df (pd.DataFrame): Daten
    spalte (str): Spaltenname

    Rückgabe:
    float: Durchschnittswert
    """
    return df[spalte].mean()

def filtere_vip(df, spalte, werte):
    """
    Filtert VIP-Kunden basierend auf einer Liste von Namen.

    Parameter:
    df (pd.DataFrame): Daten
    spalte (str): Spaltenname für Namen
    werte (list): Liste der VIP-Namen

    Rückgabe:
    pd.DataFrame: Gefilterte Daten
    """
    return df[df[spalte].isin(werte)]

• Docstrings erklären Funktion, Parameter und Rückgabe
• Teammitglieder oder Tools wie Jupyter Notebook können direkt Dokumentation anzeigen

---

9. Weitere Best Practices in Data Science

1. Aussagekräftige Variablennamen – alter statt x
2. Modularer Code – Funktionen statt lange Skripte
3. Kommentare sparsam, aber prägnant – Code sollte selbsterklärend sein
4. Versionierung / Git – Änderungen nachvollziehbar machen
5. Automatisierte Checks – Linter wie flake8 oder pylint