Python – Programmcode richtig kommentieren

Du bist noch neu in der Welt des Programmierens in Python unterwegs? Und du fragst dich, wie man den eigenen Code richtig kommentiert? Was sind Kommentare überhaupt? Wie verwende ich diese?

Es gibt 3 Typen von Kommentaren in Python, diese wollen wir hier erklären – und anschließende, nach dem du weißt, wie man syntaktisch richtig Kommentare schreibt, werfen wir noch einmal ein Blick darauf, was gehört überhaupt in einen Kommentar?

Typen von Kommentaren in Python

Es gibt verschiedene Arten von Kommentaren in Python – diese wollen wir uns nun einmal anschauen. Diese ist ein einfacher Einzeiler Kommentar in Python. Ein Kommentar wird in Python bei dieser Variante immer mit einem # (Doppelkreuz, Raute, Nummernzeichen, Hash(tag)) begonnen. Das Ende des Kommentars in Python wird mit den Zeilen ende definiert.

# this is a comment, in a single line in python!

Folgende Variante ist in Python bei der Verwendung falsch, diese sieht du auch am fehlerhaften Syntax Highlight. Und zwar wie oben schon kurz beschrieben Ende ein Kommentar in Python mit dem Zeilenende. Richtig wäre es also, wie ich es in der rechten Spalte geschrieben habe.

Die Kommentare in Python müssen nicht immer am Anfang der Zeile beginnen, Sie können überall beginnen, es kann nur nicht in derselben Zeile noch Programm Code folgen.

def add(a,b):
    return a + b # Es wird A mit B Addiert. 

Ein weiterer Typ von Kommentaren in Python sind sogenannte DocStrings diese sind eine Eigenheit von Python – diese sind nicht nur für Kommentare gedacht und können Hilfestellungen für Funktionen bereitstellen, sondern können auch als mehrzeilige Strings verwendet werden.

def helloWorld():
    output = """
        Das ist ein mehrzeiliger String,
        dieser geht über mehrere Zeilen.
    """

    print(output)

DocStrings haben zusätzliche Funktionalitäten – die bei „normalen“ Strings (Zeichenketten) nicht vorhanden sind. Eine dieser magischen Werte ist das __doc__ Property, diese beinhaltet den DocString vom Anfang der Funktion oder auch Klasse.

def world():
    """
    world is a function that returns a string world.
    """

    return "world"

print(world.__doc__)

Eine weitere Möglichkeit, sich den DocString ausgeben zu lassen, ist unter anderem die help Funktion. Als Beispiel das ganze einmal von einer Klasse dort können dann auch noch die DocStrings der Methoden ausgegeben werden.

class world:
    """
    this is a test
    """

    def __init__(self) -> None:
        pass

help(world)

Die Ausgabe im Terminal könnte dann wie folgt aussehen von der help Funktion.

Help on class world in module __main__:

class world(builtins.object)
 |  world() -> None
 |  
 |  this is a test
 |  
 |  Methods defined here:
 |  
 |  __init__(self) -> None
 |      Initialize self.  See help(type(self)) for accurate signature.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
~
(END)

So kannst du dir on the fly einfache Dokumentation ausgeben lassen. Es gibt verschiedene Tools wie: sphinx, pdoc oder pydoctor die dir das ganze noch weiter vereinfachen können, wenn du ein HTML Output für eine Dokumentation im Web oder besser gesagt in einer Optisch ansprechenderen weise haben willst.

Wobei Sphinx mit der reStructuredText Markup Language eine der am Verbreitesten möglichkeiten ist seine Python Dokumentation zu erstellen. Optisch find ich persönlich pdoc noch sehr ansprechend.

Wann also welche Kommentare verwenden?

Die DocStrings sollten nur für die Dokumentation deines Codes verwendet werden, um diesen anderen in einer Dokumentation zugänglich zu machen, sei es mit pdoc oder sphinx. Die Kommentare, die mit einem # anfangen, sollten, für das allgemeine Verständnis von spezifischen Bereichen verwendet werden.

Kann ich Kommentare verwenden, um meinen Code auszukommentieren, den ich zurzeit nicht benötige?

Häufig, gerade zu Anfang neigt man dazu, seinen Code auszukommentieren, den man nicht mehr benötigt. Gerade zu Anfang, um später noch darauf zu schließen, wie man seinen Lösungsweg gefunden hat, mag das eben in Ordnung sein. Später sollte man sich diese aber definitiv verkneifen und lernen mit einer Versionsverwaltung wie Git zu arbeiten. So kann man jede Zeile wieder herstellen, die man einmal geschrieben hat.

To-do Kommentare?

Andere Entwickler:innen arbeiten häufig mit sogenannten To-do-Kommentaren, die an Stellen gesetzt werden, wo noch etwas zu erledigen ist. Wenn man diese für einen kurzen Moment setzt, um einen größeren Bereich zu überarbeiten (Refactoring) empfinde ich das als vollkommen valide, aber sollten die Änderungen dann doch nicht in einem Commit erledigt werden können. Empfinde ich es als Sinnvoller ein entsprechendes Issue in seinem Projektmanagement oder Repository zu öffnen – so hast du alle offen Punkte an einem Ort zusammengefasst. Je nach Unternehmen hast du dafür im Beruf natürlich auch noch einmal spezifischerer Vorgaben.

Saubere Benennung – Spart dir Kommentare

Achte darauf deine Funktionen und Variablen so zu nennen, dass diese auch schon für sich sprechen können. Zum Beispiel nennen eine Funktion für das Addieren von zwei Werten nicht nur a, weil es eben kürzer und vermeintlich schöner für dich ist. Sondern schreibe dann direkt add für das englische Wort vom Addieren. So benötigst du keinen Kommentar erst einmal, der erklär, wo für das a jetzt steht. Anderes Beispiel ist eine Variable r enthält, die jetzt den Request oder Response? Genau, es weiß keiner, es müsste kommentiert werden. Also achte auf eindeutige und spezifische Benennungen, um so weniger Kommentare benötigst du, da dein Code in vielen Punkten schon für sich sprechen wird.

Fazit

Es gibt viele verschiedenen Möglichkeiten Kommentare zu setzen, für Anfänger:innen würde ich empfehlen, sich erst einmal auf das Programmieren zu konzentrieren und den Code so zu kommentieren, dass dieser für einen selbst verständlich wird und bleibt, wenn man ihn ein paar Monate später wieder offen hat.

Für etwas fortgeschrittenere Personen würde ich empfehlen zu versuchen immer sauberer aber auch reduzierter zu kommentieren auf die wichtigsten Punkte. Und mehr DocStrings zu Schreiben, die einer Dokumentation entsprechen und sich auch hier vorher klare Vorgaben zu definieren an die man sich halten möchte.