Code-Stilrichtlinien¶

Dieser Leitfaden enthält Informationen und Richtlinien zum Schreiben von Code für BeeWare.

Codierungsstil¶

BeeWare folgt PEP 8 in unserer Codebasis, außer dass die Zeilenlänge von 79 auf 88 Zeichen erweitert wurde. Wir verwenden Ruff, um die PEP 8-Konventionen nach Möglichkeit durchzusetzen. Wenn Sie Ihren Code committen, führt pre-commit Überprüfungen durch, darunter auch Ruff. Wenn möglich, wird Ihr Code automatisch formatiert, um sicherzustellen, dass er unseren Formatierungs- und Stilstandards entspricht. Sie können einige IDEs so einrichten, dass Ruff beim Speichern automatisch ausgeführt wird, was den Prozess erleichtern kann.

Denken Sie daran, dass der wichtigste Teil von PEP 8 Abschnitt 0: Eine törichte Konsistenz ist der Kobold der Kleingeister ist. Es gibt Situationen, in denen es keinen Sinn macht, sich an PEP 8 zu halten, und es ist wichtig zu verstehen, dass es akzeptabel und manchmal sogar vorzuziehen ist, Code zu schreiben, der nicht mit den aufgeführten Regeln übereinstimmt. Zu wissen, wann man sich nicht an diese Regeln halten sollte, ist in den meisten Situationen genauso wichtig wie die Einhaltung der Konsistenz.

Dies zeigt sich unter anderem in den Namenskonventionen. BeeWare-Bibliotheken müssen häufig eine Brücke zu anderen Sprachen schlagen. Beim Erstellen von Wrappern für andere Sprachen ist es wünschenswert (und in manchen Fällen sogar erforderlich), die Namenskonventionen der Zielsprache zu befolgen und nicht die von Python. Wenn beispielsweise Java-Code aufgerufen oder referenziert wird, sollten Funktionen der in Java bevorzugten Schreibweise mixedCase folgen und nicht der in PEP 8 empfohlenen Schreibweise snake_case.

Wir halten uns bei der Benennung von APIs, Variablen usw. an die US-Rechtschreibung.

Es gibt außerdem einige BeeWare-spezifische Ergänzungen zu PEP 8:

Auch wenn die Typangabe gemäß PEP 484 optional ist, wird sie nach wie vor dringend empfohlen, insbesondere bei öffentlichen API-Schnittstellen.

Nachfolgend finden Sie ein Beispiel für eine Standardfunktionsdefinition mit korrekten Typangaben und einem Sphinx-Docstring:

def function_name(param1: int, param2: str) -> bool:
"""Beispielfunktion mit Typen und einer Docstring.

:param param1: Der erste Parameter.
:param param2: Der zweite Parameter.

:returns: Der Rückgabewert. True bei Erfolg, andernfalls False.
"""

Aufteilung langer Funktionsaufrufe¶

Wenn ein Funktionsaufruf mit mehr als einem Argument nicht in eine einzige Zeile passt, setzen Sie jedes Argument in eine eigene Zeile und fügen Sie am Ende des letzten Arguments ein Komma ein. Ruff erlaubt (und schlägt vor) eine Formatierung mit mehreren Argumenten in einer umgebrochenen Zeile:

my_function(
    arg1, arg2, arg3
)

Dieser Stil sollte nicht verwendet werden. Verteilen Sie die Argumente stattdessen auf jeweils eine Zeile, indem Sie am Ende des letzten Arguments ein Komma setzen:

my_function(
    arg1,
    arg2,
    arg3,
)

Lange Zeichenfolgen aufteilen¶

Wenn ein String-Argument auf mehrere Zeilen aufgeteilt werden muss, um die Anforderungen an die Zeilenlänge zu erfüllen, setzen Sie die verketteten String-Literale in Klammern, damit klar ist, dass es sich um ein einziges Argument handelt. Das heißt, wir bevorzugen:

my_function(
    (
 "Dies ist eine sehr lange Zeichenfolge"
 "die über zwei Zeilen verteilt ist"
    ),
    second_argument,
)

übersetzt:

my_function(
    "Dies ist eine sehr lange Zeichenfolge",
    "die über zwei Zeilen verteilt ist",
    second_argument,
)

Zu vermeidende Dinge¶

Wir versuchen, "utils"-Module so weit wie möglich zu vermeiden, mit dem Verständnis, dass sie manchmal unvermeidbar sind. Die bevorzugte Alternative ist, die Funktion an anderer Stelle im Quellcode zu finden, anstatt ein "utils"-Modul zu verwenden.

Generell versuchen wir, teuren Initialisierungscode zu vermeiden oder aufzuschieben, um einen schnelleren Start der App zu erreichen. Beispielsweise werden Module im toga-core-Paket „lazy loaded“ – sie werden erst bei Bedarf importiert und nicht alle im Voraus. Dies beschleunigt den Start und es wird nur Zeit für das aufgewendet, was die App tatsächlich nutzt.

Vermeiden Sie beim Verfassen von Kommentaren die Verwendung von Pronomen der ersten Person Plural wie „wir“ (schreiben Sie beispielsweise „Loop over“ statt „We loop over“).

Geben Sie in den Test-Docstrings das erwartete Verhalten an, das der jeweilige Test demonstriert. Verzichten Sie auf Einleitungen wie „Tests, dass“ oder „Stellt sicher, dass“.

Verwenden Sie Ticket-Referenzen für schwer fassbare Probleme, bei denen das Ticket zusätzliche Details enthält, die sich nicht ohne Weiteres in Docstrings oder Kommentaren beschreiben lassen. Fügen Sie die Ticketnummer am Ende eines Satzes wie folgt ein:

def test_foo():
 """Ein Test-Docstring sieht so aus (#123456)."""