TOC

So schreiben Sie schönen Python-Code mit PEP 8

So schreiben Sie schönen Python-Code mit PEP 8

PEP 8, manchmal PEP8 oder PEP-8 geschrieben, ist ein Dokument, das Richtlinien und Best Practices zum Schreiben von Python-Code enthält. Es wurde 2001 von Guido van Rossum, Barry Warsaw und Nick Coghlan geschrieben. Das Hauptaugenmerk von PEP 8 liegt auf der Verbesserung der Lesbarkeit und Konsistenz von Python-Code.

PEP steht für Python Enhancement Proposal, und es gibt mehrere davon. Ein PEP ist ein Dokument, das die für Python vorgeschlagenen neuen Funktionen beschreibt und Aspekte von Python wie Design und Stil für die Community dokumentiert.

Dieses Tutorial beschreibt die wichtigsten Richtlinien in PEP 8. Es richtet sich an Anfänger bis Fortgeschrittene. Daher habe ich einige der fortgeschrittensten Themen nicht behandelt. Sie können dies erfahren, indem Sie die vollständige Dokumentation zuPEP 8lesen.

By the end of this tutorial, you’ll be able to:

  • Schreiben Sie Python-Code, der PEP 8 entspricht

  • Verstehen Sie die Gründe für die Richtlinien in PEP 8

  • Richten Sie Ihre Entwicklungsumgebung so ein, dass Sie mit dem Schreiben von PEP 8-kompatiblem Python-Code beginnen können

Free Bonus:5 Thoughts On Python Mastery, ein kostenloser Kurs für Python-Entwickler, der Ihnen die Roadmap und die Denkweise zeigt, die Sie benötigen, um Ihre Python-Fähigkeiten auf die nächste Stufe zu bringen.

Warum wir PEP 8 brauchen

"Lesbarkeit zählt."

-The Zen of Python

PEP 8 dient zur Verbesserung der Lesbarkeit von Python-Code. Aber warum ist Lesbarkeit so wichtig? Warum ist das Schreiben von lesbarem Code eines der Leitprinzipien der Python-Sprache?

Wie Guido van Rossum sagte: "Code wird viel häufiger gelesen als geschrieben." Sie können einige Minuten oder einen ganzen Tag damit verbringen, einen Code zu schreiben, um die Benutzerauthentifizierung zu verarbeiten. Sobald Sie es geschrieben haben, werden Sie es nie wieder schreiben. Aber Sie müssen es auf jeden Fall noch einmal lesen. Dieser Code bleibt möglicherweise Teil eines Projekts, an dem Sie arbeiten. Jedes Mal, wenn Sie zu dieser Datei zurückkehren, müssen Sie sich daran erinnern, was dieser Code bewirkt und warum Sie ihn geschrieben haben. Daher ist die Lesbarkeit wichtig.

Wenn Sie Python noch nicht kennen, kann es schwierig sein, sich einige Tage oder Wochen nach dem Schreiben zu merken, was ein Code bewirkt. Wenn Sie PEP 8 folgen, können Sie sicher sein, dass Sie Ihre Variablen gut benannt haben. Sie werden wissen, dass Sie genügend Leerzeichen hinzugefügt haben, damit Sie den logischen Schritten in Ihrem Code leichter folgen können. Sie haben Ihren Code auch gut kommentiert. All dies bedeutet, dass Ihr Code besser lesbar ist und leichter wieder aufgerufen werden kann. Als Anfänger kann das Befolgen der Regeln von PEP 8 das Erlernen von Python zu einer viel angenehmeren Aufgabe machen.

Das Befolgen von PEP 8 ist besonders wichtig, wenn Sie nach einem Entwicklungsjob suchen. Das Schreiben von klarem, lesbarem Code zeigt Professionalität. Es wird einem Arbeitgeber mitteilen, dass Sie verstehen, wie Sie Ihren Code gut strukturieren können.

Wenn Sie mehr Erfahrung mit dem Schreiben von Python-Code haben, müssen Sie möglicherweise mit anderen zusammenarbeiten. Das Schreiben von lesbarem Code ist hier von entscheidender Bedeutung. Andere Personen, die Sie möglicherweise noch nie zuvor getroffen oder Ihren Codierungsstil gesehen haben, müssen Ihren Code lesen und verstehen. Wenn Sie Richtlinien haben, die Sie befolgen und erkennen, können andere Ihren Code leichter lesen.

Regeln der Namensgebung

"Explizit ist besser als implizit."

-The Zen of Python

Wenn Sie Python-Code schreiben, müssen Sie viele Dinge benennen: Variablen, Funktionen, Klassen, Pakete usw. Wenn Sie vernünftige Namen wählen, sparen Sie später Zeit und Energie. Sie können anhand des Namens herausfinden, was eine bestimmte Variable, Funktion oder Klasse darstellt. Sie vermeiden auch die Verwendung unangemessener Namen, die zu Fehlern führen können, die schwer zu debuggen sind.

Note: Verwenden Sie niemalsl,O oderI Einzelbuchstaben, da diese je nach Schriftart mit1 und0 verwechselt werden können :: 

O = 2  # This may look like you're trying to reassign 2 to zero

Stile benennen

In der folgenden Tabelle sind einige der gängigen Namensstile im Python-Code aufgeführt und wann Sie sie verwenden sollten:

Type Namenskonvention Beispiele

Funktion

Verwenden Sie ein oder mehrere Kleinbuchstaben. Trennen Sie Wörter durch Unterstriche, um die Lesbarkeit zu verbessern.

function,my_function

Variable

Verwenden Sie einen einzelnen Buchstaben, ein Wort oder Wörter in Kleinbuchstaben. Trennen Sie Wörter mit Unterstrichen, um die Lesbarkeit zu verbessern.

x,var,my_variable

Klasse

Beginnen Sie jedes Wort mit einem Großbuchstaben. Trennen Sie Wörter nicht durch Unterstriche. Dieser Stil wird Kamelkoffer genannt.

Model,MyClass

Methode

Verwenden Sie ein oder mehrere Kleinbuchstaben. Trennen Sie Wörter mit Unterstrichen, um die Lesbarkeit zu verbessern.

class_method,method

Konstante

Verwenden Sie einen einzelnen Großbuchstaben, ein Wort oder Wörter. Trennen Sie Wörter mit Unterstrichen, um die Lesbarkeit zu verbessern.

CONSTANT,MY_CONSTANT,MY_LONG_CONSTANT

Modul

Verwenden Sie ein kurzes Wort oder Wörter in Kleinbuchstaben. Trennen Sie Wörter mit Unterstrichen, um die Lesbarkeit zu verbessern.

module.py,my_module.py

Paket

Verwenden Sie ein kurzes Wort oder Wörter in Kleinbuchstaben. Trennen Sie Wörter nicht durch Unterstriche.

package,mypackage

Dies sind einige der gängigen Namenskonventionen und Beispiele für deren Verwendung. Um jedoch lesbaren Code zu schreiben, müssen Sie bei der Auswahl der Buchstaben und Wörter vorsichtig sein. Neben der Auswahl der richtigen Namensstile in Ihrem Code müssen Sie auch die Namen sorgfältig auswählen. Im Folgenden finden Sie einige Hinweise, wie Sie dies so effektiv wie möglich tun können.

So wählen Sie Namen aus

Die Auswahl von Namen für Ihre Variablen, Funktionen, Klassen usw. kann eine Herausforderung sein. Sie sollten beim Schreiben von Code eine Menge Gedanken in Ihre Namensauswahl einfließen lassen, da dies Ihren Code lesbarer macht. Der beste Weg, um Ihre Objekte in Python zu benennen, besteht darin, beschreibende Namen zu verwenden, um zu verdeutlichen, was das Objekt darstellt.

Wenn Sie Variablen benennen, könnten Sie versucht sein, einfache, aus Kleinbuchstaben bestehende Kleinbuchstaben wiex auszuwählen. Wenn Sie jedoch nichtx als Argument für eine mathematische Funktion verwenden, ist nicht klar, wasx darstellt. Stellen Sie sich vor, Sie speichern den Namen einer Person als Zeichenfolge und möchten das Schneiden von Zeichenfolgen verwenden, um ihren Namen anders zu formatieren. Sie könnten mit so etwas enden:

>>> 

>>> # Not recommended
>>> x = 'John Smith'
>>> y, z = x.split()
>>> print(z, y, sep=', ')
'Smith, John'

Dies wird funktionieren, aber Sie müssen nachverfolgen, wasx,y undz darstellen. Es kann auch für Mitarbeiter verwirrend sein. Eine viel klarere Wahl der Namen wäre ungefähr so:

>>> 

>>> # Recommended
>>> name = 'John Smith'
>>> first_name, last_name = name.split()
>>> print(last_name, first_name, sep=', ')
'Smith, John'

Um die Anzahl der Eingaben zu verringern, kann es verlockend sein, bei der Auswahl von Namen Abkürzungen zu verwenden. Im folgenden Beispiel habe ich eine Funktiondb() definiert, die ein einzelnes Argumentx verwendet und es verdoppelt: 

# Not recommended
def db(x):
    return x * 2

Auf den ersten Blick scheint dies eine vernünftige Wahl zu sein. db() könnte leicht eine Abkürzung für double sein. Aber stellen Sie sich vor, Sie kommen in ein paar Tagen auf diesen Code zurück. Möglicherweise haben Sie vergessen, was Sie mit dieser Funktion erreichen wollten, und das würde es schwierig machen zu erraten, wie Sie sie abgekürzt haben.

Das folgende Beispiel ist viel klarer. Wenn Sie einige Tage nach dem Schreiben auf diesen Code zurückkommen, können Sie den Zweck dieser Funktion weiterhin lesen und verstehen: 

# Recommended
def multiply_by_two(x):
    return x * 2

Die gleiche Philosophie gilt für alle anderen Datentypen und Objekte in Python. Versuchen Sie immer, möglichst präzise, ​​aber aussagekräftige Namen zu verwenden.

Code-Layout

"Schön ist besser als hässlich."

-The Zen of Python

Wie Sie Ihren Code gestalten, spielt eine große Rolle für die Lesbarkeit. In diesem Abschnitt erfahren Sie, wie Sie vertikale Leerzeichen hinzufügen, um die Lesbarkeit Ihres Codes zu verbessern. Außerdem erfahren Sie, wie Sie mit dem in PEP 8 empfohlenen Zeilenumfang von 79 Zeichen umgehen.

Leere Zeilen

Vertikale Leerzeichen oder Leerzeilen können die Lesbarkeit Ihres Codes erheblich verbessern. Zusammengebündelter Code kann überwältigend und schwer zu lesen sein. In ähnlicher Weise sehen zu viele leere Zeilen in Ihrem Code sehr spärlich aus, und der Leser muss möglicherweise mehr als nötig scrollen. Im Folgenden finden Sie drei wichtige Richtlinien zur Verwendung vertikaler Leerzeichen.

Surround top-level functions and classes with two blank lines. Funktionen und Klassen der obersten Ebene sollten ziemlich eigenständig sein und separate Funktionen verarbeiten. Es ist sinnvoll, zusätzlichen vertikalen Raum um sie herum zu platzieren, damit klar ist, dass sie getrennt sind: 

class MyFirstClass:
    pass


class MySecondClass:
    pass


def top_level_function():
    return None

Surround method definitions inside classes with a single blank line. Innerhalb einer Klasse sind alle Funktionen miteinander verbunden. Es wird empfohlen, nur eine einzige Zeile zwischen ihnen zu lassen: 

class MyClass:
    def first_method(self):
        return None

    def second_method(self):
        return None

Use blank lines sparingly inside functions to show clear steps. Manchmal muss eine komplizierte Funktion mehrere Schritte vor der Anweisungreturn ausführen. Um dem Leser das Verständnis der Logik innerhalb der Funktion zu erleichtern, kann es hilfreich sein, zwischen den einzelnen Schritten eine Leerzeile zu lassen.

Im folgenden Beispiel gibt es eine Funktion zum Berechnen der Varianz einer Liste. Dies ist ein zweistufiges Problem, daher habe ich jeden Schritt angezeigt, indem ich eine Leerzeile zwischen ihnen gelassen habe. Es gibt auch eine Leerzeile vor der Anweisungreturn. Auf diese Weise kann der Leser klar erkennen, was zurückgegeben wurde: 

def calculate_variance(number_list):
    sum_list = 0
    for number in number_list:
        sum_list = sum_list + number
    mean = sum_list / len(number_list)

    sum_squares = 0
    for number in number_list:
        sum_squares = sum_squares + number**2
    mean_squares = sum_squares / len(number_list)

    return mean_squares - mean**2

Wenn Sie vertikale Leerzeichen sorgfältig verwenden, kann dies die Lesbarkeit Ihres Codes erheblich verbessern. Es hilft dem Leser visuell zu verstehen, wie sich Ihr Code in Abschnitte aufteilt und wie diese Abschnitte zueinander in Beziehung stehen.

Maximale Leitungslänge und Zeilenumbruch

In PEP 8 wird vorgeschlagen, die Zeilen auf 79 Zeichen zu beschränken. Dies liegt daran, dass Sie mehrere Dateien nebeneinander öffnen können und gleichzeitig Zeilenumbrüche vermeiden können.

Es ist natürlich nicht immer möglich, Aussagen auf 79 Zeichen oder weniger zu beschränken. In PEP 8 werden Möglichkeiten beschrieben, wie Anweisungen über mehrere Zeilen ausgeführt werden können.

Python geht von einer Zeilenfortsetzung aus, wenn Code in Klammern, Klammern oder Klammern enthalten ist: 

def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one

Wenn es nicht möglich ist, implizite Fortsetzung zu verwenden, können Sie stattdessen Backslashes verwenden, um Linien zu brechen: 

from mypkg import example1, \
    example2, example3

Wenn Sie jedoch implizite Fortsetzung verwenden können, sollten Sie dies tun.

Wenn Zeilenumbrüche um binäre Operatoren wie+ und* auftreten müssen, sollte dies vor dem Operator erfolgen. Diese Regel stammt aus der Mathematik. Mathematiker sind sich einig, dass das Brechen vor binären Operatoren die Lesbarkeit verbessert. Vergleichen Sie die folgenden zwei Beispiele.

Unten finden Sie ein Beispiel für das Brechen vor einem Binäroperator: 

# Recommended
total = (first_variable
         + second_variable
         - third_variable)

Sie können sofort sehen, welche Variable hinzugefügt oder subtrahiert wird, da sich der Operator direkt neben der Variablen befindet, mit der gearbeitet wird.

Sehen wir uns nun ein Beispiel für das Brechen nach einem Binäroperator an: 

# Not Recommended
total = (first_variable +
         second_variable -
         third_variable)

Hier ist es schwieriger zu erkennen, welche Variable hinzugefügt und welche subtrahiert wird.

Das Unterbrechen vor binären Operatoren erzeugt besser lesbaren Code, daher wird er von PEP 8 empfohlen. Code, derconsistently bricht, nachdem ein Binäroperator noch PEP 8-kompatibel ist. Es wird jedoch empfohlen, vor einem Binäroperator zu brechen.

Vertiefung

"Es sollte einen - und vorzugsweise nur einen - offensichtlichen Weg geben, dies zu tun."

-The Zen of Python

Einrückungen oder führende Leerzeichen sind in Python äußerst wichtig. Die Einrückungsstufe von Codezeilen in Python bestimmt, wie Anweisungen zusammen gruppiert werden.

Betrachten Sie das folgende Beispiel: 

x = 3
if x > 5:
    print('x is larger than 5')

Die eingerückte Anweisungprint teilt Python mit, dass sie nur ausgeführt werden soll, wenn die AnweisungifTrue zurückgibt. Der gleiche Einzug gilt, um Python mitzuteilen, welcher Code ausgeführt werden soll, wenn eine Funktion aufgerufen wird oder welcher Code zu einer bestimmten Klasse gehört.

Die wichtigsten Einrückungsregeln in PEP 8 lauten wie folgt:

  • Verwenden Sie 4 aufeinanderfolgende Leerzeichen, um die Einrückung anzuzeigen.

  • Ziehen Sie Leerzeichen gegenüber Tabulatoren vor.

Tabs vs. Räume

Wie oben erwähnt, sollten Sie beim Einrücken von Code Leerzeichen anstelle von Tabulatoren verwenden. Sie können die Einstellungen in Ihrem Texteditor so anpassen, dass 4 Leerzeichen anstelle eines Tabulatorzeichens ausgegeben werden, wenn Sie die Taste # (t0) s # drücken.

Wenn Sie Python 2 verwenden und eine Mischung aus Tabulatoren und Leerzeichen zum Einrücken Ihres Codes verwendet haben, werden beim Ausführen keine Fehler angezeigt. Um die Konsistenz zu überprüfen, können Sie beim Ausführen von Python 2-Code über die Befehlszeile ein-t-Flag hinzufügen. Der Interpreter gibt Warnungen aus, wenn Sie mit der Verwendung von Tabulatoren und Leerzeichen nicht einverstanden sind: 

$ python2 -t code.py
code.py: inconsistent use of tabs and spaces in indentation

Wenn Sie stattdessen das Flag-ttverwenden, gibt der Interpreter anstelle von Warnungen Fehler aus und Ihr Code wird nicht ausgeführt. Der Vorteil dieser Methode besteht darin, dass der Interpreter Ihnen mitteilt, wo die Inkonsistenzen liegen: 

$ python2 -tt code.py
  File "code.py", line 3
    print(i, j)
             ^
TabError: inconsistent use of tabs and spaces in indentation

Python 3 erlaubt kein Mischen von Tabulatoren und Leerzeichen. Wenn Sie Python 3 verwenden, werden diese Fehler daher automatisch ausgegeben: 

$ python3 code.py
  File "code.py", line 3
    print(i, j)
              ^
TabError: inconsistent use of tabs and spaces in indentation

Sie können Python-Code mit Tabulatoren oder Leerzeichen schreiben, die Einrückungen anzeigen. Wenn Sie jedoch Python 3 verwenden, müssen Sie mit Ihrer Auswahl übereinstimmen. Andernfalls wird Ihr Code nicht ausgeführt. In PEP 8 wird empfohlen, immer 4 aufeinanderfolgende Leerzeichen zu verwenden, um die Einrückung anzuzeigen.

Einrückung nach Zeilenumbrüchen

Wenn Sie Zeilenfortsetzungen verwenden, um Zeilen auf weniger als 79 Zeichen zu beschränken, ist es hilfreich, Einrückungen zu verwenden, um die Lesbarkeit zu verbessern. Es ermöglicht dem Leser, zwischen zwei Codezeilen und einer einzelnen Codezeile zu unterscheiden, die zwei Zeilen umfasst. Es gibt zwei Arten von Einrückungen, die Sie verwenden können.

Die erste davon besteht darin, den eingerückten Block am Öffnungsbegrenzer auszurichten: 

def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one

Manchmal können Sie feststellen, dass nur 4 Leerzeichen erforderlich sind, um am Eröffnungsbegrenzer auszurichten. Dies tritt häufig inif-Anweisungen auf, die sich über mehrere Zeilen erstrecken, daif, Leerzeichen und öffnende Klammern 4 Zeichen umfassen. In diesem Fall kann es schwierig sein zu bestimmen, wo der verschachtelte Codeblock in der Anweisungifbeginnt: 

x = 5
if (x > 3 and
    x < 10):
    print(x)

In diesem Fall bietet PEP 8 zwei Alternativen zur Verbesserung der Lesbarkeit:

  • Fügen Sie nach der endgültigen Bedingung einen Kommentar hinzu. Aufgrund der Hervorhebung der Syntax in den meisten Editoren werden die Bedingungen vom verschachtelten Code getrennt: 

    x = 5
if (x > 3 and
    x < 10):
    # Both conditions satisfied
    print(x)

  • Fügen Sie der Zeilenfortsetzung zusätzliche Einrückungen hinzu: 

    x = 5
if (x > 3 and
        x < 10):
    print(x)

Ein alternativer Einrückungsstil nach einem Zeilenumbruch isthanging indent. Dies ist ein typografischer Begriff, der bedeutet, dass jede Zeile außer der ersten in einem Absatz oder einer Anweisung eingerückt ist. Sie können einen hängenden Einzug verwenden, um eine Fortsetzung einer Codezeile visuell darzustellen. Hier ist ein Beispiel: 

var = function(
    arg_one, arg_two,
    arg_three, arg_four)

Note: Wenn Sie einen hängenden Einzug verwenden, dürfen in der ersten Zeile keine Argumente stehen. Das folgende Beispiel ist nicht PEP 8-kompatibel: 

# Not Recommended
var = function(arg_one, arg_two,
    arg_three, arg_four)

Wenn Sie einen hängenden Einzug verwenden, fügen Sie einen zusätzlichen Einzug hinzu, um die fortgesetzte Zeile von dem in der Funktion enthaltenen Code zu unterscheiden. Das folgende Beispiel ist schwer zu lesen, da sich der Code in der Funktion auf derselben Einrückungsstufe befindet wie die fortgesetzten Zeilen: 

# Not Recommended
def function(
    arg_one, arg_two,
    arg_three, arg_four):
    return arg_one

Stattdessen ist es besser, einen doppelten Einzug für die Zeilenfortsetzung zu verwenden. Auf diese Weise können Sie zwischen Funktionsargumenten und dem Funktionskörper unterscheiden und die Lesbarkeit verbessern: 

def function(
        arg_one, arg_two,
        arg_three, arg_four):
    return arg_one

Wenn Sie PEP 8-kompatiblen Code schreiben, werden Sie aufgrund der Zeilenbegrenzung von 79 Zeichen gezwungen, Zeilenumbrüche in Ihren Code einzufügen. Um die Lesbarkeit zu verbessern, sollten Sie eine fortgesetzte Zeile einrücken, um anzuzeigen, dass es sich um eine fortgesetzte Zeile handelt. Es gibt zwei Möglichkeiten, dies zu tun. Der erste besteht darin, den eingerückten Block am Öffnungsbegrenzer auszurichten. Die zweite besteht darin, einen hängenden Einzug zu verwenden. Sie können frei wählen, welche Einrückungsmethode Sie nach einem Zeilenumbruch verwenden.

Wo wird die Verschlussklammer angebracht?

Mit Linienfortsetzungen können Sie Linien in Klammern, Klammern oder Klammern brechen. Es ist leicht, die schließende Klammer zu vergessen, aber es ist wichtig, sie an einem vernünftigen Ort zu platzieren. Andernfalls kann der Leser verwirrt werden. PEP 8 bietet zwei Optionen für die Position der schließenden Klammer in impliziten Linienfortsetzungen:

  • Richten Sie die schließende Klammer mit dem ersten Nicht-Leerzeichen der vorherigen Zeile aus: 

    list_of_numbers = [
    1, 2, 3,
    4, 5, 6,
    7, 8, 9
    ]

  • Richten Sie die schließende Klammer mit dem ersten Zeichen der Zeile aus, mit der das Konstrukt beginnt: 

    list_of_numbers = [
    1, 2, 3,
    4, 5, 6,
    7, 8, 9
]

Sie können frei wählen, welche Option Sie verwenden. Aber wie immer ist Konsistenz der Schlüssel, also versuchen Sie, sich an eine der oben genannten Methoden zu halten.

"Wenn die Implementierung schwer zu erklären ist, ist das eine schlechte Idee."

-The Zen of Python

Sie sollten Kommentare verwenden, um den Code so zu dokumentieren, wie er geschrieben wurde. Es ist wichtig, Ihren Code zu dokumentieren, damit Sie und alle Mitarbeiter ihn verstehen können. Wenn Sie oder eine andere Person einen Kommentar liest, sollte sie in der Lage sein, den Code, auf den sich der Kommentar bezieht, leicht zu verstehen und zu verstehen, wie er zum Rest Ihres Codes passt.

Hier sind einige wichtige Punkte, die Sie beim Hinzufügen von Kommentaren zu Ihrem Code beachten sollten:

  • Begrenzen Sie die Zeilenlänge von Kommentaren und Dokumentzeichenfolgen auf 72 Zeichen.

  • Verwenden Sie vollständige Sätze, beginnend mit einem Großbuchstaben.

  • Stellen Sie sicher, dass Sie die Kommentare aktualisieren, wenn Sie Ihren Code ändern.

Verwenden Sie Blockkommentare, um einen kleinen Codeabschnitt zu dokumentieren. Sie sind nützlich, wenn Sie mehrere Codezeilen schreiben müssen, um eine einzelne Aktion auszuführen, z. B. das Importieren von Daten aus einer Datei oder das Aktualisieren eines Datenbankeintrags. Sie sind wichtig, da sie anderen helfen, den Zweck und die Funktionalität eines bestimmten Codeblocks zu verstehen.

PEP 8 enthält die folgenden Regeln zum Schreiben von Blockkommentaren:

  • Blockkommentare auf dieselbe Ebene wie den von ihnen beschriebenen Code einrücken.

  • Beginnen Sie jede Zeile mit einem#, gefolgt von einem einzelnen Leerzeichen.

  • Trennen Sie Absätze durch eine Zeile, die ein einzelnes# enthält.

Hier ist ein Blockkommentar, der die Funktion einerfor-Schleife erklärt. Beachten Sie, dass der Satz in eine neue Zeile umgebrochen wird, um das Zeilenlimit von 79 Zeichen beizubehalten: 

for i in range(0, 10):
    # Loop over i ten times and print out the value of i, followed by a
    # new line character
    print(i, '\n')

Wenn der Code sehr technisch ist, muss manchmal mehr als ein Absatz in einem Blockkommentar verwendet werden: 

def quadratic(a, b, c, x):
    # Calculate the solution to a quadratic equation using the quadratic
    # formula.
    #
    # There are always two solutions to a quadratic equation, x_1 and x_2.
    x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a)
    x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a)
    return x_1, x_2

Wenn Sie jemals Zweifel haben, welcher Kommentartyp geeignet ist, sind Blockkommentare häufig der richtige Weg. Verwenden Sie sie so oft wie möglich in Ihrem Code, aber aktualisieren Sie sie unbedingt, wenn Sie Änderungen an Ihrem Code vornehmen!

Inline-Kommentare erklären eine einzelne Anweisung in einem Code. Sie sind nützlich, um Sie daran zu erinnern oder anderen zu erklären, warum eine bestimmte Codezeile erforderlich ist. Hier ist, was PEP 8 dazu zu sagen hat:

  • Verwenden Sie Inline-Kommentare sparsam.

  • Schreiben Sie Inline-Kommentare in dieselbe Zeile wie die Anweisung, auf die sie sich beziehen.

  • Trennen Sie Inline-Kommentare durch zwei oder mehr Leerzeichen von der Anweisung.

  • Beginnen Sie Inline-Kommentare mit einem# und einem einzelnen Leerzeichen, z. B. Blockkommentare.

  • Verwenden Sie sie nicht, um das Offensichtliche zu erklären.

Unten finden Sie ein Beispiel für einen Inline-Kommentar: 

x = 5  # This is an inline comment

Manchmal scheinen Inline-Kommentare notwendig zu sein, aber Sie können stattdessen bessere Namenskonventionen verwenden. Hier ist ein Beispiel: 

x = 'John Smith'  # Student Name

Hier gibt der Inline-Kommentar zusätzliche Informationen. Die Verwendung vonx als Variablenname für den Namen einer Person ist jedoch eine schlechte Praxis. Der Inline-Kommentar ist nicht erforderlich, wenn Sie Ihre Variable umbenennen: 

student_name = 'John Smith'

Schließlich sind Inline-Kommentare wie diese eine schlechte Praxis, da sie den offensichtlichen und unübersichtlichen Code enthalten: 

empty_list = []  # Initialize empty list

x = 5
x = x * 5  # Multiply x by 5

Inline-Kommentare sind spezifischer als Blockkommentare und können einfach hinzugefügt werden, wenn sie nicht erforderlich sind, was zu Unordnung führt. Sie könnten davonkommen, nur Blockkommentare zu verwenden. Wenn Sie nicht sicher sind, dass Sie einen Inline-Kommentar benötigen, ist es wahrscheinlicher, dass Ihr Code PEP 8-kompatibel ist, wenn Sie sich an Blockkommentare halten.

Dokumentationszeichenfolgen

Dokumentationszeichenfolgen oder Dokumentzeichenfolgen sind Zeichenfolgen, die in doppelte (""") oder einfache (''') Anführungszeichen eingeschlossen sind und in der ersten Zeile einer Funktion, Klasse, Methode oder eines Moduls erscheinen. Sie können sie verwenden, um einen bestimmten Codeblock zu erklären und zu dokumentieren. Es gibt einen vollständigen PEP,PEP 257, der Dokumentzeichenfolgen abdeckt. In diesem Abschnitt erhalten Sie jedoch eine Zusammenfassung.

Die wichtigsten Regeln für Dokumentzeichenfolgen sind folgende:

  • Umgeben Sie Dokumentzeichenfolgen mit drei doppelten Anführungszeichen auf beiden Seiten, wie in"""This is a docstring""".

  • Schreiben Sie sie für alle öffentlichen Module, Funktionen, Klassen und Methoden.

  • Setzen Sie die""", die einen mehrzeiligen Dokumentstring beenden, in eine eigene Zeile: 

    def quadratic(a, b, c, x):
    """Solve quadratic equation via the quadratic formula.

    A quadratic equation has the following form:
    ax**2 + bx + c = 0

    There always two solutions to a quadratic equation: x_1 & x_2.
    """
    x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a)
    x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a)

    return x_1, x_2

  • Behalten Sie für einzeilige Dokumentzeichenfolgen die""" in derselben Zeile bei: 

    def quadratic(a, b, c, x):
    """Use the quadratic formula"""
    x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a)
    x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a)

    return x_1, x_2

Ein ausführlicherer Artikel zur Dokumentation von Python-Code finden Sie unterDocumenting Python Code: A Complete Guide von James Mertz.

Leerzeichen in Ausdrücken und Anweisungen

"Sparse ist besser als dicht."

-The Zen of Python

Whitespace kann bei korrekter Verwendung in Ausdrücken und Anweisungen sehr hilfreich sein. Wenn nicht genügend Leerzeichen vorhanden sind, kann es schwierig sein, Code zu lesen, da alles zusammengeballt ist. Wenn zu viele Leerzeichen vorhanden sind, kann es schwierig sein, verwandte Begriffe in einer Anweisung visuell zu kombinieren.

Leerzeichen um Binäroperatoren

Umgeben Sie die folgenden Binäroperatoren mit einem Leerzeichen auf beiden Seiten:

  • Zuweisungsoperatoren (=,+=,-= usw.)

  • Vergleiche (==,!=,>,<. >=,<=) und (is,is not,in,not in)

  • Boolesche Werte (and,not,or)

Note: Wenn= verwendet wird, um einem Funktionsargument einen Standardwert zuzuweisen, umgeben Sie ihn nicht mit Leerzeichen. 

# Recommended
def function(default_parameter=5):
    # ...


# Not recommended
def function(default_parameter = 5):
    # ...

Wenn eine Anweisung mehr als einen Operator enthält, kann das Hinzufügen eines einzelnen Leerzeichens vor und nach jedem Operator verwirrend aussehen. Stattdessen ist es besser, nur Leerzeichen um die Operatoren mit der niedrigsten Priorität hinzuzufügen, insbesondere wenn mathematische Manipulationen durchgeführt werden. Hier einige Beispiele: 

# Recommended
y = x**2 + 5
z = (x+y) * (x-y)

# Not Recommended
y = x ** 2 + 5
z = (x + y) * (x - y)

Sie können dies auch aufif-Anweisungen anwenden, bei denen mehrere Bedingungen vorliegen: 

# Not recommended
if x > 5 and x % 2 == 0:
    print('x is larger than 5 and divisible by 2!')

Im obigen Beispiel hat der Operatoranddie niedrigste Priorität. Es kann daher klarer sein, die Aussage vonifwie folgt auszudrücken: 

# Recommended
if x>5 and x%2==0:
    print('x is larger than 5 and divisible by 2!')

Sie können frei wählen, was klarer ist, mit der Einschränkung, dass Sie auf beiden Seiten des Operators dieselbe Menge an Leerzeichen verwenden müssen.

Folgendes ist nicht akzeptabel: 

# Definitely do not do this!
if x >5 and x% 2== 0:
    print('x is larger than 5 and divisible by 2!')

In Slices fungieren Doppelpunkte als binäre Operatoren. Daher gelten die im vorherigen Abschnitt beschriebenen Regeln, und auf beiden Seiten sollte die gleiche Anzahl von Leerzeichen vorhanden sein. Die folgenden Beispiele für Listenschnitte sind gültig: 

list[3:4]

# Treat the colon as the operator with lowest priority
list[x+1 : x+2]

# In an extended slice, both colons must be
# surrounded by the same amount of whitespace
list[3:4:5]
list[x+1 : x+2 : x+3]

# The space is omitted if a slice parameter is omitted
list[x+1 : x+2 :]

Zusammenfassend sollten Sie die meisten Operatoren mit Leerzeichen umgeben. Diese Regel weist jedoch einige Einschränkungen auf, z. B. bei Funktionsargumenten oder beim Kombinieren mehrerer Operatoren in einer Anweisung.

Wann sollte das Hinzufügen von Leerzeichen vermieden werden?

In einigen Fällen kann das Hinzufügen von Leerzeichen das Lesen von Code erschweren. Zu viel Leerzeichen kann dazu führen, dass Code zu spärlich und schwer zu befolgen ist. In PEP 8 werden sehr klare Beispiele aufgeführt, bei denen Leerzeichen unangemessen sind.

Der wichtigste Ort, um das Hinzufügen von Leerzeichen zu vermeiden, ist das Ende einer Zeile. Dies ist alstrailing whitespace bekannt. Es ist unsichtbar und kann zu Fehlern führen, die schwer zu verfolgen sind.

In der folgenden Liste sind einige Fälle aufgeführt, in denen Sie das Hinzufügen von Leerzeichen vermeiden sollten:

  • Sofort in Klammern, Klammern oder Klammern: 

    # Recommended
my_list = [1, 2, 3]

# Not recommended
my_list = [ 1, 2, 3, ]

  • Vor einem Komma, Semikolon oder Doppelpunkt: 

    x = 5
y = 6

# Recommended
print(x, y)

# Not recommended
print(x , y)

  • Vor der offenen Klammer, die die Argumentliste eines Funktionsaufrufs startet: 

    def double(x):
    return x * 2

# Recommended
double(3)

# Not recommended
double (3)

  • Vor der offenen Klammer, die einen Index oder ein Slice startet: 

    # Recommended
list[3]

# Not recommended
list [3]

  • Zwischen einem nachgestellten Komma und einer schließenden Klammer: 

    # Recommended
tuple = (1,)

# Not recommended
tuple = (1, )

  • So richten Sie Zuweisungsoperatoren aus: 

    # Recommended
var1 = 5
var2 = 6
some_long_var = 7

# Not recommended
var1          = 5
var2          = 6
some_long_var = 7

Stellen Sie sicher, dass in Ihrem Code keine nachgestellten Leerzeichen vorhanden sind. In anderen Fällen rät PEP 8 davon ab, zusätzliche Leerzeichen hinzuzufügen, z. B. unmittelbar in Klammern sowie vor Kommas und Doppelpunkten. Sie sollten auch niemals zusätzliche Leerzeichen hinzufügen, um Operatoren auszurichten.

Programmierempfehlungen

"Einfach ist besser als komplex."

-The Zen of Python

Sie werden häufig feststellen, dass es in Python (und jeder anderen Programmiersprache) mehrere Möglichkeiten gibt, eine ähnliche Aktion auszuführen. In diesem Abschnitt sehen Sie einige der Vorschläge, die PEP 8 zur Beseitigung dieser Mehrdeutigkeit und zur Wahrung der Konsistenz enthält.

Don’t compare boolean values to True or False using the equivalence operator. Sie müssen häufig überprüfen, ob ein boolescher Wert wahr oder falsch ist. Wenn Sie dies tun, ist es intuitiv, dies mit einer Aussage wie der folgenden zu tun: 

# Not recommended
my_bool = 6 > 5
if my_bool == True:
    return '6 is bigger than 5'

Die Verwendung des Äquivalenzoperators== ist hier nicht erforderlich. bool kann nur WerteTrue oderFalse annehmen. Es reicht aus, folgendes zu schreiben: 

# Recommended
if my_bool:
    return '6 is bigger than 5'

Diese Art, eineif-Anweisung mit einem Booleschen Wert auszuführen, erfordert weniger Code und ist einfacher, daher empfiehlt PEP 8 dies.

Use the fact that empty sequences are falsy in if statements. Wenn Sie überprüfen möchten, ob eine Liste leer ist, könnten Sie versucht sein, die Länge der Liste zu überprüfen. Wenn die Liste leer ist, beträgt ihre Länge0, wasFalse entspricht, wenn sie in einerif-Anweisung verwendet wird. Hier ist ein Beispiel: 

# Not recommended
my_list = []
if not len(my_list):
    print('List is empty!')

In Python ist jedoch jede leere Liste, Zeichenfolge oder jedes Tupelfalsy. Wir können daher eine einfachere Alternative zu den oben genannten finden: 

# Recommended
my_list = []
if not my_list:
    print('List is empty!')

Während beide BeispieleList is empty! ausdrucken, ist die zweite Option einfacher, daher empfiehlt PEP 8 dies.

Use is not rather than not ... is in if statements. Wenn Sie überprüfen möchten, ob eine Variable einen definierten Wert hat, gibt es zwei Optionen. Die erste besteht darin, eineif-Anweisung mitx is not None zu bewerten, wie im folgenden Beispiel: 

# Recommended
if x is not None:
    return 'x exists!'

Eine zweite Möglichkeit wäre,x is None zu bewerten und dann eineif-Anweisung basierend aufnot als Ergebnis zu erhalten: 

# Not recommended
if not x is None:
    return 'x exists!'

Während beide Optionen korrekt bewertet werden, ist die erste einfacher, daher wird sie von PEP 8 empfohlen.

Don’t use if x: when you mean if x is not None:. Manchmal haben Sie möglicherweise eine Funktion mit Argumenten, die standardmäßigNone sind. Ein häufiger Fehler bei der Überprüfung, ob einem solchen Argument,arg, ein anderer Wert zugewiesen wurde, ist die Verwendung des folgenden: 

# Not Recommended
if arg:
    # Do something with arg...

Dieser Code überprüft, obarg wahr ist. Stattdessen möchten Sie überprüfen, obargnot None ist. Verwenden Sie daher besser Folgendes: 

# Recommended
if arg is not None:
    # Do something with arg...

Der Fehler, der hier gemacht wird, ist die Annahme, dassnot None und Wahrheit gleich sind. Sie hättenarg = [] setzen können. Wie wir oben gesehen haben, werden leere Listen in Python als falsch ausgewertet. Obwohl das Argumentarg zugewiesen wurde, ist die Bedingung nicht erfüllt, und der Code im Hauptteil der Anweisungifwird nicht ausgeführt.

Use .startswith() and .endswith() instead of slicing. Wenn Sie versuchen zu überprüfen, ob einer Zeichenfolgeword das Wortcat vorangestellt oder mit einem Suffix versehen wurde, erscheint es möglicherweise sinnvoll,list slicing zu verwenden. Das Aufteilen von Listen ist jedoch fehleranfällig, und Sie müssen die Anzahl der Zeichen im Präfix oder Suffix fest codieren. Es ist auch jemandem nicht klar, der weniger mit Python-Listen vertraut ist, was Sie erreichen möchten: 

# Not recommended
if word[:3] == 'cat':
    print('The word starts with "cat"')

Dies ist jedoch nicht so lesbar wie die Verwendung von.startswith(): 

# Recommended
if word.startswith('cat'):
    print('The word starts with "cat"')

Ebenso gilt das gleiche Prinzip, wenn Sie nach Suffixen suchen. Das folgende Beispiel zeigt, wie Sie überprüfen können, ob eine Zeichenfolge mitjpg endet: 

# Not recommended
if file_name[-3:] == 'jpg':
    print('The file is a JPEG')

Während das Ergebnis korrekt ist, ist die Notation etwas klobig und schwer zu lesen. Stattdessen können Sie.endswith() wie im folgenden Beispiel verwenden: 

# Recommended
if file_name.endswith('jpg'):
    print('The file is a JPEG')

Wie bei den meisten dieser Programmierempfehlungen ist das Ziel Lesbarkeit und Einfachheit. In Python gibt es viele verschiedene Möglichkeiten, dieselbe Aktion auszuführen. Daher sind Richtlinien für die Auswahl der Methoden hilfreich.

Wann PEP 8 zu ignorieren ist

Die kurze Antwort auf diese Frage lautet nie. Wenn Sie PEP 8 genau befolgen, können Sie sicherstellen, dass Sie über sauberen, professionellen und lesbaren Code verfügen. Davon profitieren Sie ebenso wie Mitarbeiter und potenzielle Arbeitgeber.

Einige Richtlinien in PEP 8 sind jedoch in den folgenden Fällen unpraktisch:

  • Wenn die Einhaltung von PEP 8 die Kompatibilität mit vorhandener Software beeinträchtigen würde

  • Wenn der Code für Ihre Arbeit nicht mit PEP 8 übereinstimmt

  • Wenn Code mit älteren Versionen von Python kompatibel bleiben muss

Tipps und Tricks, um sicherzustellen, dass Ihr Code PEP 8 entspricht

Es gibt viel zu beachten, um sicherzustellen, dass Ihr Code PEP 8-kompatibel ist. Es kann eine große Aufgabe sein, sich bei der Entwicklung von Code an all diese Regeln zu erinnern. Es ist besonders zeitaufwändig, frühere Projekte so zu aktualisieren, dass sie PEP 8-konform sind. Glücklicherweise gibt es Tools, die diesen Prozess beschleunigen können. Es gibt zwei Klassen von Tools, mit denen Sie die PEP 8-Konformität erzwingen können: Linters und Autoformatters.

Linters

Linters sind Programme, die Code- und Flag-Fehler analysieren. Sie enthalten Vorschläge zur Behebung des Fehlers. Linters sind besonders nützlich, wenn sie als Erweiterungen für Ihren Texteditor installiert werden, da sie beim Schreiben Fehler und Stilprobleme anzeigen. In diesem Abschnitt sehen Sie eine Übersicht über die Funktionsweise der Linters mit Links zu den Texteditor-Erweiterungen am Ende.

Die besten Linters für Python-Code sind die folgenden:

  • pycodestyle ist ein Tool zum Überprüfen Ihres Python-Codes anhand einiger Stilkonventionen in PEP 8.

    Installieren Siepycodestyle mitpip: 

    $ pip install pycodestyle

    Sie könnenpycodestyle vom Terminal aus mit dem folgenden Befehl ausführen: 

    $ pycodestyle code.py
code.py:1:17: E231 missing whitespace after ','
code.py:2:21: E231 missing whitespace after ','
code.py:6:19: E711 comparison to None should be 'if cond is None:'

  • flake8 ist ein Tool, das einen Debuggerpyflakes mitpycodestyle kombiniert.

    Installieren Sieflake8 mitpip: 

    $ pip install flake8

    Führen Sieflake8 mit dem folgenden Befehl vom Terminal aus: 

    $ flake8 code.py
code.py:1:17: E231 missing whitespace after ','
code.py:2:21: E231 missing whitespace after ','
code.py:3:17: E999 SyntaxError: invalid syntax
code.py:6:19: E711 comparison to None should be 'if cond is None:'

    Ein Beispiel für die Ausgabe wird ebenfalls gezeigt.

Note: Die zusätzliche Ausgabezeile zeigt einen Syntaxfehler an.

Diese sind auch als Erweiterungen fürAtom,Sublime Text,https://code.visualstudio.com/docs/python/linting#flake8[Visual Studio Code], and VIM. You can also find guides on setting up Sublime Text and VIM for Python development, as well as an overview of some popular text editors at _Real Python verfügbar.

Autoformatters

Autoformatters sind Programme, die Ihren Code so umgestalten, dass er automatisch mit PEP 8 übereinstimmt. Sobald ein solches Programmblack ist, formatiert es den Code automatisch nachmost der Regeln in PEP 8. Ein großer Unterschied besteht darin, dass die Zeilenlänge auf 88 statt auf 79 Zeichen begrenzt wird. Sie können dies jedoch überschreiben, indem Sie ein Befehlszeilenflag hinzufügen, wie Sie in einem Beispiel unten sehen werden.

Installieren Sieblack mitpip. Zum Ausführen ist Python 3.6+ erforderlich: 

$ pip install black

Es kann wie bei den Lintern über die Kommandozeile ausgeführt werden. Angenommen, Sie beginnen mit dem folgenden Code, der in einer Datei mit dem Namencode.py nicht PEP 8-kompatibel ist: 

for i in range(0,3):
    for j in range(0,3):
        if (i==2):
            print(i,j)

Sie können dann den folgenden Befehl über die Befehlszeile ausführen: 

$ black code.py
reformatted code.py
All done! ✨ 🍰 ✨

code.py werden automatisch neu formatiert, um folgendermaßen auszusehen: 

for i in range(0, 3):
    for j in range(0, 3):
        if i == 2:
            print(i, j)

Wenn Sie die Zeilenlängenbeschränkung ändern möchten, können Sie das Flag--line-length verwenden: 

$ black --line-length=79 code.py
reformatted code.py
All done! ✨ 🍰 ✨

Zwei andere Autoformatierer,autopep8 undyapf, führen Aktionen aus, die denen vonblack ähnlich sind.

Ein weiteres Tutorial vonReal Python,Python Code Quality: Tools & Best Practices von Alexander van Tol, enthält eine ausführliche Erklärung zur Verwendung dieser Tools.

Fazit

Sie wissen jetzt, wie Sie qualitativ hochwertigen, lesbaren Python-Code mithilfe der in PEP 8 festgelegten Richtlinien schreiben. Während die Richtlinien pedantisch erscheinen können, kann das Befolgen dieser Richtlinien Ihren Code wirklich verbessern, insbesondere wenn es darum geht, Ihren Code mit potenziellen Arbeitgebern oder Mitarbeitern zu teilen.

In diesem Tutorial haben Sie gelernt:

  • Was ist PEP 8 und warum existiert es?

  • Warum sollten Sie versuchen, PEP 8-kompatiblen Code zu schreiben?

  • So schreiben Sie Code, der PEP 8-kompatibel ist

Darüber hinaus haben Sie gesehen, wie Sie mithilfe von Lintern und Autoformattern Ihren Code anhand der PEP 8-Richtlinien überprüfen.

Wenn Sie mehr über PEP 8 erfahren möchten, können Sie diefull documentation lesen oderpep8.org besuchen, die dieselben Informationen enthalten, aber gut formatiert wurden. In diesen Dokumenten finden Sie den Rest der PEP 8-Richtlinien, die in diesem Lernprogramm nicht behandelt werden.

Related