Python-Programme in Projektarbeit entwickeln

Verwende 4 Leerzeichen pro Einrückungsebene.

Fortsetzungszeilen sollten umhüllte Elemente entweder vertikal mit der impliziten Linie von Python ausrichten, die in Klammern (), eckigen Klammern [] oder geschweiften Klammern {} zusammengefügt wird, oder mit einer hängenden Einrückung. Bei der Verwendung einer hängenden Einrückung ist folgendes zu beachten: In der ersten Zeile sollten keine Argumente vorhanden sein und weitere Einzüge sollten verwendet werden, um sich klar als Fortsetzungszeile zu unterscheiden.

# ausgerichtet an einem oeffnenden Begrenzer - hier (
wert = langer_funktions_name(parameter1, parameter2, parameter3,
                             parameter4, parameter5)
                             
# alternativ mindestens ein haengender Einzug mit 4 Leerzeichen
wert = langer_funktions_name(parameter1, parameter2, parameter3,
    parameter4, parameter5)

# vier Leerzeichen zusaetzlich (zusaetzliche Einrueckung), um 
# Parameter vom Rest zu trennen.
def langer_funktions_name(
        parameter1, parameter2, parameter3, parameter4, parameter5):
    print(parameter1)
    print(parameter2)
    

Alle Zeilen sollte auf 79 Zeichen begrenzt werden (80 mit Zeilenumbruchzeichen).

Für lange Textblöcke oder Kommentare sollte die Zeilenlänge auf 72 Zeichen begrenzt werden.

Die Begrenzung der erforderlichen Editorfensterbreite ermöglicht es, mehrere Dateien nebeneinander auf einem Bildschirm zu öffnen.

Die Python-Standardbibliothek ist konservativ und erfordert eine Begrenzung der Zeilen auf 79 Zeichen (und der Docstrings/Kommentare auf 72), deshalb muss jeder, der im Python-Projekt mitwirken möchte, die 79-Zeichen-Regel befolgen.

Die bevorzugte Art, lange Zeilen zu umbrechen, ist die Verwendung von Pythons impliziter Zeilenfortsetzung innerhalb von allen Klammerarten oder bei der Verwendung von Operatoren. Lange Zeilen können über mehrere Zeilen gebrochen werden, indem Ausdrücke in Klammern eingeschlossen werden. Diese sollten anstelle eines Backslash für die Zeilenfortsetzung verwendet werden.

Backslashes können manchmal noch angemessen sein, sollten aber vermieden werden.

# Zeilenumbrueche bei Operatoren
einkommen = bruttoeinkommen
            + honoprare
            + zinseinkommen
            + dividenden
            - steuern
            - sozialabgaben

# Zeilenumbrueche bei der Verwendung von Klammern aller Arten
meine_liste = [
    eins, zwei, drei,
    vier, fuenf, sechs,
    ]

# oder alternativ kann die schliessende Klammer unter dem ersten Zeichen
# der Zeile stehen, die das mehrzeilige Konstrukt startet.
meine_liste = [
    eins, zwei, drei,
    vier, fuenf, sechs,
]

# Wenn keine der vorstehenden Moeglichkeiten reicht, nutze den Backslash.
# Zeilenumbuechen mit Backslash sollten vermieden werden
with open('/path/to/some/file/you/want/to/read') as file_1,   \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

Grundsätzlich sollte man bei Python3 immer UTF-8 nutzen.

Nicht-ASCII-Zeichen sind dann erlaubt, wenn ein Kommentar oder ein Docstring einen Autoren*innennamen erwähnen muss, deren Namen auf dem lateinischen Alphabet basieren (lateinisch-1, ISO/IEC 8859-1 Zeichensatz).

Umgebe die oberste Funktions- und Klassendefinition mit zwei Leerzeilen.

Methodendefinitionen innerhalb einer Klasse werden von einer einzigen Leerzeile umgeben.

Zusätzliche Leerzeilen können (sparsam) verwendet werden, um Gruppen von verwandten Funktionen zu trennen.

Verwende Leerzeilen in Funktionen sparsam, um logische Abschnitte zu kennzeichnen.

Die folgenden Beispiele zeigen wie es sein sollte.

# Keine Leerzeichen direkt vor Klammer
# richtig
spam(ham[1], {eggs: 2})
# falsch
spam( ham[ 1 ], { eggs: 2 } )

# Nie zwischen letztem Komma und schließender Klammer
# richtig
werte = (0, 1,)
# falsch
werte = (0, 1, )

# Nicht unmittelbar vor einem Komma, Semikolon oder Doppelpunkt
# richtig
if x == 4:
    print x, y
    x, y = y, x
# falsch
if x == 4 :
    print x , y
    x , y = y , x

# Sonderfall Slices
# In einem Slice verhält sich der Doppelpunkt jedoch wie ein binärer
# Operator und sollte auf beiden Seiten gleiche Mengen aufweisen
# (er wird als der Operator mit der niedrigsten Priorität behandelt).
# In einem erweiterten Slice müssen beide Doppelpunkte den gleichen
# Abstand aufweisen. Ausnahme: Wenn ein Slice-Parameter weggelassen wird,
# wird der Platz weggelassen.
# richtig
ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower+offset : upper+offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower + offset : upper + offset]
# falsch
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]

# Kein Leerzeichen nmittelbar vor der offenen Klammer, die die
# Argumentenliste eines Funktionsaufrufs startet.
# richtig
fp = open("/pfad/auf/meine/datei")
# falsch
fp = open ("/pfad/auf/meine/datei")

# Keine Leerzeichen unmittelbar vor der offenen Klammer, die eine
# Indexierung oder ein Slicing startet.
# richtig
namenliste['schluessel'] = lst[index]
#falsch
namenliste ['schluessel'] = lst [index]

# Nicht mehr als ein Leerzeichen um einen zugewiesenen (oder anderen)
# Operator herum, um ihn miteinander auszurichten.
# richtig
x = 1
y = 2
langer_name = 3
# falsch
x           = 1
y           = 2
langer_name = 3

# -----------------------------
# Allgemeine weitere Vorschläge
#
# Meide überall "nachschleppende" Leerzeichen am Zeilenende

# Folgende Operatoren immer mit einem Leerzeichen umgeben
# Zuweisungen (=)
# Erweiterte Zuweisungen (+=, -=, etc.)
# Vergleiche (==, <, >, !=, <>, <=, >=, in, not in, is, is not)
# Bool’sche Ausdrücke (and, or, not)

# Leerzeichen bei Operatoren mit unterschiedlichen Prioritäten
# Wenn Operatoren mit unterschiedlichen Prioritäten verwendet werden,
# empfiehlt es sich, Leerzeichen um die Operatoren mit der niedrigsten
# Priorität(en) hinzuzufügen. Verwende dein eigenes Urteilsvermögen;
# jedoch nie mehr als ein Leerzeichen und habe immer die gleiche Menge
# an Leerzeichen auf beiden Seiten eines binären Operators.
# richtig
i = i + 1
zaehler += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
# falsch
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

In Python sind einfach (') angeführte Strings und doppelt (") angeführte Strings identisch. Dies PEP8 gibt keine Empfehlung dazu ab. Wähle eine Regel und halte dich daran. Wenn eine Zeichenkette jedoch einfache oder doppelte Anführungszeichen enthält, verwendet das andere, um Backslashes in der Zeichenkette zu vermeiden. Es verbessert die Lesbarkeit.

Verwende bei Zeichenketten mit drei Anführungszeichen immer doppelte Anführungszeichen, um mit der Docstring-Konvention in PEP 257 (siehe unten) konsistent zu sein.

Jede import-Anweisung sollte auf einer eigenen Zeile stehen.

# richtig
import sys
import math
from random import randint
from turtle import *
from machine import PIN  # Modul eine Fremdanbieters
from mein_modul import meine_funktion

# akzeptabel ist
from math import sin, cos, tan
from mein_modul import meine_funktionq, meine_funktion2

Import-Anweisungen sollten immer ganz oben in der Datei platziert sein, direkt nach Modulkommentaren und den Docstrings.
Also immer auch vor Globalen und Konstanten.

Importe sollten in der folgenden Reihenfolge zusammengefasst werden:

Standardbibliotheken Importe
Importe von nahestehenden Drittanbietern
Lokale Anwendung / bibliotheksspezifische Importe

Die Namenskonventionen der Python-Bibliothek sind ein wenig durcheinander, so dass man dies nie vollständig konsistent bekommen wird – dennoch hier sind die derzeit empfohlenen Namensstandards. Neue Module und Pakete (einschließlich Frameworks von Drittanbietern) sollten nach diesen Standards geschrieben werden, aber wenn eine bestehende Bibliothek einen anderen Stil hat, wird die interne Konsistenz bevorzugt.

Vorrangiges Prinzip

Namen, die für den Benutzer als öffentliche Teile sichtbar sind, sollten Konventionen folgen, die die Verwendung und nicht die Implementierung widerspiegeln.

Benennungsstile

Es gibt viele verschiedene Namensstile. Es hilft zu erkennen, welcher Namensstil verwendet wird, unabhängig davon, wofür er verwendet wird.

Die folgenden Benennungsstile werden häufig unterschieden (hier die sehr oft auftauchenden englischen Fachbegriffe):

• b (single lowercase letter)
• B (single uppercase letter)
• lowercase
• lower_case_with_underscores
• UPPERCASE
• UPPER_CASE_WITH_UNDERSCORES
• CapitalizedWords (oder CapWords oder CamelCase). Sonderfall Acronyme: HTTPServerError ist besser als HttpServerError.
• mixedCase (im Unterschied zu CapitalizedWords ist der erste Buchstabe klein geschrieben!)

Es gibt auch den Stil, ein kurzes eindeutiges Präfix zu verwenden, um verwandte Namen zusammenzufassen. Dies wird in Python nicht oft verwendet, wird aber der Vollständigkeit halber erwähnt. Zum Beispiel gibt die Funktion os.stat() ein Tupel zurück, dessen Elemente traditionell Namen wie st_mode, st_size, st_mtime und so weiter haben.

Namenskonventionen

Zu vermeidende Namen

Benutze niemals die Zeichen ‚l‘ (Kleinbuchstabe el), ‚O‘ (Großbuchstabe oh) oder ‚I‘ (Großbuchstabe i) als einzelnes Zeichen für Variablennamen.

In einigen Schriftarten sind diese Zeichen von den Ziffern eins und null nicht zu unterscheiden. Wenn du versucht bist, ‚l‘ zu benutzen, benutze stattdessen ‚L‘.

ASCII-Kompatibilität

Die in der Standardbibliothek verwendeten Bezeichner müssen ASCII-kompatibel sein. Das gilt auch für alle im Net-Schulbuch verwendeten Namen.

Modulnamen

Module sollten kurze, klein geschriebene Namen haben. Unterstriche können im Modulnamen verwendet werden, wenn sie die Lesbarkeit verbessern. 

Klassennamen

Klassennamen sollten normalerweise die CapWords-Konvention verwenden.

Funktionennamen

Funktionennamen werden klein geschrieben: lowercase oder lower_case_with_underscores oder mixedCase 

Variablenbezeichnungen

Variablennamen werden klein geschrieben: lowercase oder lower_case_with_underscores oder mixedCase 

Globale Variablennamen

(Hoffentlich sind diese Variablen nur für die Verwendung innerhalb eines Moduls gedacht.)

Module, die für die Verwendung über den M-Import * konzipiert sind, sollten, um den Export von Globals zu verhindern, die Konvention verwenden, solche Globals mit einem Unterstrich zu versehen.

Methodennamen und Instanzvariablen

Zur besseren Lesbarkeit sollten Kleinbuchstaben mit Wörtern, die bei Bedarf durch Unterstriche getrennt sind.

Benutze nur einen führenden Unterstrich für nicht-öffentliche Methoden und Instanzvariablen.

Konstanten

Konstanten werden in der Regel auf Modulebene definiert und in Großbuchstaben mit unterstrichenen Trennwörtern geschrieben.
Beispiele sind MAX_OVERFLOW und TOTAL.

Unterscheide: Kommentar, Blockkommentar und DocString

Kommentar

Einzeilige Kommentage werden mit # eingeleitet und im Programmtext mit der aktuellen Einrückung versehen. 

Blockkommentar

Blockkommentare umfassen mehrere Zeilen (lso einen Block). Sie werden von jeweils drei Anführungszeichen eingerahmt.

Es können sowohl einfache als auch doppelte Anführungszeichen verwendet werden (Hauptsache: einheitlich). 

DocString

Ein DocString ist ein Blockkommentar, der aber nur an festgelegten Stellen Stelle in der Datei als DocString interpretiert wird.
DocStrings sollten auf jeden Fall mit drei doppelten Anführungszeichen umrahmt werden.

Diese Stellen sind:

• am Anfang einer Programmdatei (Modul-DocString)
• direkt unter einer Klassendefinition (Klassen-DocString)
• direkt unter einer Funktions- oder Methodendefinition (Funktions/Methoden-DocString)

Konventionen zum Schreiben guter Dokumentationszeichenketten (auch bekannt als „docstrings“) sind in PEP 257 verewigt.

Verfasse Docstrings für alle öffentlichen Module, Funktionen, Klassen und Methoden. Docstrings sind für nicht-öffentliche Methoden nicht notwendig, aber Sie sollten einen Kommentar haben, der beschreibt, was die Methode tut. Dieser Kommentar sollte nach der Def-Zeile erscheinen.

PEP 257 beschreibt gute Docstring-Konventionen. Am wichtigsten ist, dass das """ das eine mehrzeilige Docstring beendet, in einer eigenen Zeile stehen sollte.Bei einzeiligen Docstrings halte bitte das Schließen """ auf der gleichen Zeile.

Als Beispiel wird hier ein Mustergerüst für die Dokumentation eines Moduls mit mehreren Funktionen dargestellt.

"""
Beschreibung des Moduls

Version: 0.1 vom 01.01.2020
Autor*in: net-schulbuch.de (redaktion@if1.net-schulbuch.de)
"""

def funktion1(parameter1):
    """
    funktion1 zeichnet ein rotes Quadrat
    Parameter:
        parameter1: Seitenlaenge des Quadrats
    Hinweise:
        Die untere linke Ecke ist der Ausgangspunkt.
        Zuerst wird die Quadratseite in Richtung der Turtle gezeichnet.
        Dann folgen gegen den Uhrzeigersind die uebrigen Seiten.
        Am Ende befindet sich die Turtle in demselben Zustand wie zuvor.
    """
    zustand = 'aktueller Zustand der Turtle'
    """ Der aktuelle Zustand wird zwischengespeichert."""
    setpos(parameter1)

Der Inhalt der DocStrings ist in den übersetzten binären Python-Dateien enthalten. Die DocStrings können über die help()-Funktion von Python sichtbar gemacht werden. Dies zeigen die beiden folgenden Screenshots, nachdem obige Datei nsb_docstringmuster.py.txt als Datei unter dem Namen test.py in Thonny geladen wurde. 

Man erkennt, dass der Blockkommentar zur Variablen zustand kein DocString ist, weil er nicht angezeigt wird.

Gut geschriebene Python-Programme enthalten die Dokumentation in der Quelldatei. Teile dieser Dokumentation kann man einfach sichtbar machen.