Kommentare sind Notizen, die Programmierer an ihren Code anhängen, um zu erklären, was der Code tun soll. Die Compiler oder Interpreter, die den Code in die Tat umsetzen, ignorieren Kommentare, aber sie können für die Verwaltung von Softwareprojekten wichtig sein.

Kommentare helfen dabei, anderen Programmierern deinen Python-Code zu erklären, und können dich daran erinnern, warum du die richtigen Entscheidungen getroffen hast. Kommentare erleichtern die Fehlersuche und die Überarbeitung des Codes, indem sie zukünftigen Programmierern helfen, die Designentscheidungen hinter der Software zu verstehen.

Obwohl Kommentare in erster Linie für Entwickler gedacht sind, kann das Schreiben von effektiven Kommentaren auch dabei helfen, eine hervorragende Dokumentation für die Benutzer deines Codes zu erstellen. Mit Hilfe von Dokumentgeneratoren wie Sphinx für Python-Projekte können die Kommentare in deinem Code den Inhalt für deine Dokumentation liefern.

Werfen wir nun also einen Blick auf Kommentare in Python.

Kommentare in Python

Laut dem Python PEP 8 Style Guide gibt es beim Schreiben von Kommentaren einige Dinge zu beachten:

  • Kommentare sollten immer aus vollständigen und prägnanten Sätzen bestehen.
  • Es ist besser, gar keinen Kommentar zu haben als einen, der schwer zu verstehen oder ungenau ist.
  • Kommentare sollten regelmäßig aktualisiert werden, um Änderungen an deinem Code zu berücksichtigen.
  • Zu viele Kommentare können ablenken und die Qualität des Codes verringern. Kommentare sind nicht nötig, wenn der Zweck des Codes offensichtlich ist.

In Python wird eine Zeile als Kommentar deklariert, wenn sie mit dem Symbol # beginnt. Wenn der Python-Interpreter in deinem Code auf # stößt, ignoriert er alles, was nach diesem Symbol kommt, und gibt keinen Fehler aus. Es gibt zwei Möglichkeiten, einzeilige Kommentare zu deklarieren: Inline-Kommentare und Block-Kommentare.

Inline-Kommentare

Inline-Kommentare enthalten kurze Beschreibungen von Variablen und einfachen Operationen und werden in der gleichen Zeile wie die Code-Anweisung geschrieben:

border = x + 10  # Make offset of 10px

Der Kommentar erklärt die Funktion des Codes in der gleichen Anweisung wie der Code.

Block-Kommentare

Blockkommentare werden verwendet, um komplexe Logik im Code zu beschreiben. Blockkommentare in Python sind ähnlich aufgebaut wie Inline-Kommentare – der einzige Unterschied ist, dass Blockkommentare in einer eigenen Zeile geschrieben werden:

import csv
from itertools import groupby

# Get a list of names in a sequence from the csv file
with open('new-top-firstNames.csv') as f:
    file_csv = csv.reader(f)

# Skip the header part: (sr, name, perc)
header = next(file_csv)
    
# Only name from (number, name, perc)
persons = [ x[1] for x in file_csv]

# Sort the list by first letter because 
# The groupby function looks for sequential data.
persons.sort(key=lambda x:x[0])
data = groupby(persons, key=lambda x:x[0])

# Get every name as a list 
data_grouped = {}
for k, v in data:
    # Get data in the form 
    # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]}
    data_grouped[k] = list(v)

Der einzige Unterschied ist, dass Blockkommentare in einer separaten Zeile stehen: Wenn du Blockkommentare verwendest, stehen sie über dem Code, den sie erklären. Der Python PEP8 Style Guide schreibt vor, dass eine Codezeile nicht mehr als 79 Zeichen enthalten sollte, und Inline-Kommentare überschreiten oft diese Zeilenlänge. Aus diesem Grund werden Blockkommentare geschrieben, um den Code in separaten Zeilen zu beschreiben.

Mehrzeilige Kommentare

Python unterstützt von Haus aus keine mehrzeiligen Kommentare, d.h. es gibt keine spezielle Möglichkeit, sie zu definieren. Trotzdem werden oft Kommentare verwendet, die sich über mehrere Zeilen erstrecken.

Du kannst einen mehrzeiligen Kommentar aus mehreren einzeiligen Kommentaren erstellen, indem du jeder Zeile ein # voranstellst:

# interpreter 
# ignores
# these lines

Du kannst auch die Syntax für mehrzeilige Strings verwenden. In Python kannst du mehrzeilige Strings definieren, indem du sie in """, dreifache doppelte Anführungszeichen, oder ''', dreifache einfache Anführungszeichen einschließt:

print("Multi-Line Comment")
"""
This
String is 
Multi line 
"""

Im obigen Code wird die mehrzeilige Zeichenkette keiner Variablen zugewiesen, wodurch die Zeichenkette wie ein Kommentar wirkt. Zur Laufzeit ignoriert Python die Zeichenkette, und sie wird nicht in den Bytecode aufgenommen. Wenn du den obigen Code ausführst, erhältst du die folgende Ausgabe:

Multi-Line Comment

Besondere Kommentare

Kommentare machen deinen Code nicht nur lesbar, sondern dienen in Python auch einigen besonderen Zwecken, z. B. der Planung zukünftiger Code-Ergänzungen und der Erstellung von Dokumentation.

Python Docstring-Kommentare

In Python sind Docstrings mehrzeilige Kommentare, die erklären, wie man eine bestimmte Funktion oder Klasse verwendet. Die Dokumentation deines Codes wird durch die Erstellung von hochwertigen Docstrings verbessert. Wenn du mit einer Funktion oder Klasse arbeitest und die eingebaute Funktion help(obj) verwendest, können docstrings hilfreich sein, um einen Überblick über das Objekt zu geben.

Python PEP 257 bietet eine Standardmethode zur Deklaration von Docstrings in Python, die im Folgenden dargestellt wird:

from collections import namedtuple
Person = namedtuple('Person', ['name', 'age'])

 def get_person(name, age, d=False):
    """
Returns a namedtuple("name", "age") object.
Also returns dict('name', 'age') if arg `d` is True

Arguments:
name  – first name, must be string
age   – age of person, must be int
d     – to return Person as `dict` (default=False)

"""
p = Person(name, age)
if d:
    return p._asdict()
return p

Im obigen Code liefert der Docstring Details darüber, wie die zugehörige Funktion funktioniert. Mit Dokumentationsgeneratoren wie Sphinx kann dieser Docstring verwendet werden, um den Benutzern deines Projekts einen Überblick über die Verwendung dieser Methode zu geben.

Ein Docstring, der direkt unterhalb der Funktions- oder Klassensignatur definiert ist, kann auch mit der eingebauten Funktion help() zurückgegeben werden. Die Funktion help() nimmt ein Objekt oder einen Funktionsnamen als Argument und gibt die Docstrings der Funktion als Ausgabe zurück. Im obigen Beispiel kann help(get_person) aufgerufen werden, um die mit der Funktion get_person verknüpften Docstrings anzuzeigen. Wenn du den obigen Code in einer interaktiven Shell mit dem Flag -i ausführst, kannst du sehen, wie dieser Docstring von Python geparst wird. Führe den obigen Code aus, indem du python -i file.py eingibst.

Screenshot: Python-Docstring-Kommentare werden im Terminal geparst
Python-Docstring-Kommentare werden in der Befehlszeilenschnittstelle geparst

Der Funktionsaufruf help(get_person) gibt einen Docstring für deine Funktion zurück. Die Ausgabe enthält get_person(name, age, d=False), das ist eine Funktionssignatur, die Python automatisch hinzufügt.

Das Attribut get_person.__ doc__ kann auch verwendet werden, um Docstrings programmatisch abzurufen und zu ändern. Nach dem Hinzufügen von „Some more new information“ im obigen Beispiel erscheint es im zweiten Aufruf von help(get_person). Es ist jedoch unwahrscheinlich, dass du Docstrings zur Laufzeit dynamisch ändern musst.

TODO-Kommentare

Beim Schreiben von Code kann es vorkommen, dass du bestimmte Zeilen oder ganze Blöcke markieren möchtest, um sie zu verbessern. Diese Aufgaben werden durch TODO-Kommentare gekennzeichnet. TODO-Kommentare sind praktisch, wenn du Aktualisierungen oder Änderungen an deinem Code planst oder wenn du die Benutzer oder Mitarbeiter des Projekts darüber informieren möchtest, dass bestimmte Abschnitte des Codes noch geschrieben werden müssen.

TODO-Kommentare sollten nicht als Pseudocode geschrieben werden – sie müssen nur kurz die Funktion des noch nicht geschriebenen Codes erklären.

TODO-Kommentare und einzeilige Blockkommentare sind sich sehr ähnlich. Der einzige Unterschied zwischen ihnen ist, dass TODO-Kommentare mit einem TODO-Präfix beginnen müssen:

# TODO Get serialized data from the CSV file
# TODO Perform calculations on the data
# TODO Return to the user

Obwohl viele IDEs diese Kommentare für den Programmierer hervorheben können, werden TODO-Kommentare vom Python-Interpreter nicht anders behandelt als Blockkommentare.

Best Practices beim Schreiben von Python-Kommentaren

Es gibt eine Reihe von Best Practices, die beim Schreiben von Kommentaren befolgt werden sollten, um Zuverlässigkeit und Qualität zu gewährleisten. Im Folgenden findest du einige Tipps für das Schreiben hochwertiger Kommentare in Python.

Vermeide das Offensichtliche

Kommentare, die das Offensichtliche aussprechen, bringen keinen Mehrwert für deinen Code und sollten vermieden werden. Zum Beispiel:

x = x + 4 # increase x by 4

Dieser Kommentar ist nicht nützlich, da er einfach nur angibt, was der Code macht, ohne zu erklären, warum er gemacht werden muss. Kommentare sollten eher das „Warum“ als das „Was“ des Codes erklären, den sie beschreiben.

Umgeschrieben könnte das obige Beispiel wie folgt aussehen:

x = x + 4 # increase the border width

Halte die Python-Kommentare kurz und bündig

Halte deine Kommentare kurz und leicht verständlich. Sie sollten in normaler Prosa geschrieben sein, nicht in Pseudocode, und sie sollten die Notwendigkeit ersetzen, den eigentlichen Code zu lesen, um einen allgemeinen Überblick darüber zu bekommen, was er tut. Zu viele Details oder komplexe Kommentare machen die Arbeit der Programmierer/innen nicht einfacher. Ein Beispiel:

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Der obige Kommentar enthält mehr Informationen, als für den Leser notwendig sind. Anstatt die Kernlogik zu beschreiben, sollten Kommentare eine allgemeine Zusammenfassung des Codes liefern. Dieser Kommentar kann umgeschrieben werden als:

# return area of cylinder
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Bezeichner mit Bedacht verwenden

Bezeichner sollten in Kommentaren sorgfältig verwendet werden. Das Ändern von Bezeichnernamen oder Großbuchstaben kann den Leser verwirren. Beispiel:

# return class() after modifying argument
def func(cls, arg):
    return cls(arg+5)

Im obigen Kommentar werden class und argument erwähnt, die beide nicht im Code vorkommen. Dieser Kommentar kann umgeschrieben werden in:

# return cls() after modifying arg
def func(cls, arg):
    return cls(arg+5)

DRY und WET

Wenn du Code schreibst, solltest du das DRY-Prinzip (don’t repeat yourself) einhalten und WET (write everything twice) vermeiden.

Das gilt auch für Kommentare. Vermeide es, mehrere Anweisungen zu verwenden, um deinen Code zu beschreiben, und versuche, Kommentare, die denselben Code erklären, in einem einzigen Kommentar zusammenzufassen. Beim Zusammenführen von Kommentaren musst du jedoch vorsichtig sein: Das unvorsichtige Zusammenführen mehrerer Kommentare kann zu einem riesigen Kommentar führen, der gegen die Stilrichtlinien verstößt und für den Leser schwer zu verstehen ist.

Denk daran, dass Kommentare die Lesezeit des Codes verkürzen sollen.

# function to do x work
def do_something(y):
    # x work cannot be done if y is greater than max_limit
    if y < 400:
      print('doing x work')

Im obigen Code sind die Kommentare unnötig aufgesplittert und können zu einem einzigen Kommentar zusammengefügt werden:

# function to do x if arg:y is less than max_limit
def  do_something(y):
    if y in range(400):
    if y in range(400):

Konsistente Einrückung

Achte darauf, dass die Kommentare auf der gleichen Ebene eingerückt sind wie der Code, den sie beschreiben. Wenn das nicht der Fall ist, kann es schwierig werden, ihnen zu folgen.

Dieser Kommentar ist zum Beispiel nicht richtig eingerückt oder positioniert:

for i in range(2,20, 2):
# only even numbers
    if verify(i):
# i should be verified by verify()
        perform(x)

Er kann wie folgt umgeschrieben werden:

# only even numbers
for i in range(2,20, 2):
    # i should be verified by verify()
    if verify(i):
        perform(x)

Zusammenfassung

Kommentare sind ein wichtiger Bestandteil, um verständlichen Code zu schreiben. Die Investition, die du beim Schreiben eines Kommentars hinein steckst, wird dein zukünftiges Ich – oder andere Entwickler, die an deinem Code arbeiten müssen – zu schätzen wissen. Durch Kommentare erhältst du außerdem tiefere Einblicke in deinen Code.

In diesem Tutorium hast du mehr über Kommentare in Python gelernt, einschließlich der verschiedenen Arten von Python-Kommentaren, wann du sie verwenden solltest und wie du sie am besten anlegst.

Das Schreiben von guten Kommentaren ist eine Fähigkeit, die du lernen und entwickeln musst. Um das Schreiben von Kommentaren zu üben, solltest du zu einigen deiner früheren Projekte zurückgehen und Kommentare hinzufügen. Um dich zu inspirieren und die besten Praktiken in Aktion zu sehen, schau dir gut dokumentierte Python-Projekte auf GitHub an.

Wenn du bereit bist, deine eigenen Python-Projekte in Betrieb zu nehmen, kannst du deinen Code mit der Anwendungs Hosting-Plattform von Kinsta in Sekundenschnelle von GitHub in die Cloud bringen.

Vivek Singh

Vivek ist ein Python- und Django-Entwickler, der immer bereit ist, neue Dinge zu lernen und anderen Entwicklern beizubringen.