Kommentare in Python

Kommentare sind in jeder Programmiersprache ein wichtiger Bestandteil. Sie erfüllen verschiedene Aufgaben, je nachdem wo sie eingesetzt werden. Es gibt Kommentare um Funktionen, Methoden oder Klassen zu beschreiben, aber auch Kommentare innerhalb eines Code-Blocks, die dazu dienen eine Stelle im Code näher zu erläutern.
In Python kann man auf verschiedene Weise einen Kommentar schreiben. Am einfachsten geht das mit dem # Zeichen gefolgt vom eigentlich Kommentar, der sich in der gleichen Zeile anschließt.
Möchte man über mehrere Zeilen kommentieren, so kann man entweder in jeder Zeile ein # Zeichen setzen:
oder aber man benutzt einen multiline-string, welcher mit drei Anführungszeichen eingeleitet und ebenso beendet wird:
Wie bereits angedeutet, werden die möglichen Kommentar Typen an unterschiedlichen Stellen im Code immer wieder verwendet.
Hier wird ein Line-Kommentar benutzt, um zu erklären, weshalb der nachfolgende Codeblock entsprechend aufgebaut ist:
Kommentare über mehrere Zeilen werden meist für die Dokumentation benutzt. Documentation-Strings oder kurz „docstrings“ schließen sich der Funktions- bzw Methodendefinition an.
Hier findet man die PEP8 Definitionen zu Kommentaren.
Wann welchen Kommentar Typ benutzen?
Warum gibt es in Python diese zwei verschiedenen Möglichkeiten einen Kommentar zu verfassen?
Wie schon oben erwähnt, werden die multiline-strings, die sich einer Funktions-, Methoden- oder Klassendefinition anschließen als Dokumentation interpretiert, und man sollte diese Art der Kommentare auch nur dafür einsetzen. Es gibt einige Tools, die diese Kommentare auswerten können. PyCharm z.B. benutzt die docstrings, um bei einem mouse-over diese im Kontextfenster einzublenden.
Daher sollten docstrings auch einem gewissen Format entsprechen. Zunächst sollten sie grundlegend erläutern, was die Funktion, Methode oder Klasse bewirkt, was sie verändert oder umsetzt. Bei unserem Beispiel oben, scheint der Autor das wohl nicht bedacht zu haben. Dass diese Funktion die „main“ Funktion ist, erkennt man allein schon an ihrem Namen. Was sie aber für eine Aufgabe hat, wird im docstring nicht ersichtlich. Jedoch erkennt man immerhin, welche Parameter die Funktion erwartet und was sie zurück liefert. Um diese Information in einem docstring zu setzen, kann man spezielle Schlüsselwörter benutzen.
Das oben dargestellte Format nennt sich reStructuredText (reST) (und kann von PyCharm automatisch erzeugt und z.B. über Sphinx ausgelesen werden). Docstrings dienen also allein der Dokumentation und können daher als eine Art Handbuch des Programms gesehen werden, das eventuell sogar von Nicht-Programmierern gelesen wird.
Im Gegensatz zu den docstrings stehen die „normalen“ Kommentare, die mit # gekennzeichnet sind. Diese Kommentare sollten eher dazu dienen punktuell Stellen im Quellcode näher zu erläutern. Sie sollten einem Softwareentwickler helfen, Licht ins Dunkel der Code-Zeilen zu bringen und ihm bestenfalls einen roten Faden an die Hand geben oder auf einen wesentlichen Aspekt des Codes hinweisen. Man sollte sich vor Augen halten, dass diese Kommentare von jemandem gelesen werden, der sich wenig bis gar nicht mit dem Code und dessen Kontext beschäftigt hat (z.B. ein neuer Mitarbeiter, ein externer Freelancer, aber erstaunlicher Weise oft auch man selbst) und an dieser Stelle neuen Code einfügen, eine Funktion fixen oder gar entfernen muss.
Zusammenfassung
- docstrings fürs Handbuch (was macht die Funktion, Übergabe Parameter, Rückgabe Werte)
- Kommentare für sich selbst zum Verständnis des eigentlichen Codes, insbesondere für spätere Anpassungen
Versteht man einen Kommentar nicht, dann sollte man herausfinden, was durch den Code passiert und den Kommentar anpassen. Fehlt eine Beschreibung oder ein Parameter im docstring? Auch hier sollte man auf Vollständigkeit achten und ergänzen.
Metaphorisch gesprochen ist Programmieren manchmal wie Gartenarbeit, immer wieder sieht man hier und da ein Stück Unkraut, lässt man es stehen, ist irgendwann die Pracht des Gartens vom Unkraut überwuchert. Ich zupfe also gern mal hier und da…
Originally published at einfachpython.de on July 30, 2017.
