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:

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(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

übersetzt:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    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.