Sicherstellung der Codequalität in Python-Projekten

Ein robuster Ansatz zur Sicherstellung der Codequalität in Python-Projekten umfasst mehrere Schlüsselbereiche, die von der Klarheit einzelner Methoden bis zur übergeordneten Organisation des Projekts reichen. Die konsequente Anwendung von Richtlinien für Methoden-Signaturen, Kommentare, Docstrings und die Projektstruktur legen ein solides Fundament für wartbaren und verständlichen Code.

Sprache des Codes

Obwohl das Projekt in deutscher Sprache organisiert ist und die Hauptsprache aller Projektpartner ebenfalls Deutsch ist, soll der Code und jegliche verbundene Dokumentation auf English gehalten werden. Grund dafür ist einerseits der industrielle Standard, aber auch die Ausrichtung von manchen Tools auf die englische Sprache

Methoden-Signaturen

Klare und präzise Methoden-Signaturen sind entscheidend für die Verständlichkeit und Nutzbarkeit von Funktionen und Methoden. Achte auf folgende Punkte:

Typ-Annotationen:

Verwende Typ-Annotationen (PEP 484) für alle Argumente und den Rückgabewert. Dies verbessert die Lesbarkeit und ermöglicht statische Typprüfung:

def calculate_sum(numbers: list[int]) -> int:
    """DOCSTRING OMITTED"""
    return sum(numbers)

In diesem Beispiel wurde einerseits der Typ der Input-Variable numbers als Liste von int definiert. Zudem wurde aber auch der Rückgabewert der Methode mit einem int festgelegt.

Sprechende Namen:

Wähle deskriptive Namen für Methoden und deren Parameter, die ihre Funktion und den erwarteten Datentyp klar widerspiegeln. Vermeide Abkürzungen, die nicht allgemein verständlich sind.

Standardwerte:

Nutze Standardwerte für optionale Parameter, um die Flexibilität der Methode zu erhöhen und gleichzeitig die Aufrufe in einfachen Fällen zu vereinfachen.

def greet(name: str, message: str = "Hello") -> str:
    """DOCSTRING OMITTED"""
    return f"{message}, {name}!"

Konsistenz:

Halte dich an eine einheitliche Konvention für die Reihenfolge der Parameter, konkret:

1. erforderliche Parameter zuerst
2. dann optionale Parameter

Richtlinien für Docstrings

Gut geschriebene Kommentare und Docstrings sind unerlässlich, um den Zweck, die Funktionsweise und die Nutzung von Code zu dokumentieren.

Jedes Modul, jede Klasse, jede Funktion und jede Methode sollte einen Docstring haben (PEP 257).

Modul-Docstrings:

Beschreiben den Zweck des Moduls und wichtige globale Variablen oder Funktionen.

Klassen-Docstrings:

Fassen den Zweck der Klasse zusammen und listen wichtige Attribute und Methoden auf.

Funktions- und Methoden-Docstrings:

Die erste Zeile sollte eine prägnante Zusammenfassung der Funktionalität sein. Es folgen eine ausführlichere Beschreibung, Argumente (mit Typ und Beschreibung), Rückgabewerte (mit Typ und Beschreibung) und gegebenenfalls Informationen über Ausnahmen, Seiteneffekte oder Beispiele. Verwende das Google-Style-Docstring-Format oder das NumPy/SciPy-Style-Format für eine strukturierte und gut lesbare Dokumentation.

Visual Studio Erweiterung for DocStrings

1. Installiere die VS Code Extension "autoDocstring - Python Docstring Generator"
2. Ändere in den Einstellungen von VS Code das DocString Format

• Suche in den Einstellungen nach "autoDocstring.docstringFormat"
• Ändere das Format auf "sphinx"

3. Werden nun unter einer Methoden-Signatur drei Hochkomata geschrieben, erscheint ein Autocomplete Vorschlag, der ein DocString Template erstellt

Mehr Information bezüglich des sphinx Formates können hier nachgelesen werden.

Ein typischer DocString sieht dann so aus:

def calculate_sum(numbers: list[]) -> int:
    """Calculate the sum of all numbers in the list

    :param numbers: a list containing multiple numbers
    :type numbers: list[]
    :return: the sum of all elements in the list
    :rtype: int
    """
    return sum(numbers)

Richtlinien für Kommentare

Verwende Kommentare (#) sparsam, um komplexen oder nicht-offensichtlichen Code zu erklären.

Kommentare sollten erklären, warum etwas getan wird, nicht nur was. Halte Kommentare aktuell, wenn du den Code änderst. Veraltete Kommentare können irreführend sein.

Vermeide offensichtliche Kommentare, die lediglich den Code wiederholen.