Kommentare richtig einsetzen
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 eigentlichen Kommentar, der sich in der gleichen Zeile anschließt.
# this is a simple comment, in only one line
Möchte man über mehrere Zeilen kommentieren, so kann man entweder in jeder Zeile ein # Zeichen setzen:
# comment starting in the first line
# continues in the second
# and maybe third?
oder aber man benutzt einen multiline-string, welcher mit drei Anführungszeichen eingeleitet und ebenso beendet wird:
""" this is a multi line comment
to describe some more details """
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:
# Make sure os.environ exists, at least
try:
environ
except NameError:
environ = {}
Es ist auch möglich einen Kommentar hinter einem Stück Code einzufügen, so kann man z.B. in einer Zeile den restlichen Code „ignorieren“ ohne ihn komplett entfernen zu müssen. Wir addieren die Variable b nur einmal, da der dritte Summand auskommentiert ist.
def calc(a, b):
return a + b #+ b
Kommentare über mehrere Zeilen werden meist für die Dokumentation benutzt. Documentation-Strings oder kurz „docstrings“ schließen sich der Funktions- bzw Methodendefinition an.
def removedirs(name):
"""removedirs(name)
Super-rmdir; remove a leaf directory and all empty intermediate
ones. Works like rmdir except that, if the leaf directory is
successfully removed, directories corresponding to rightmost path
segments will be pruned away until either the whole path is
consumed or an error occurs. Errors during this latter phase are
ignored -- they generally mean that a directory was not empty.
"""
rmdir(name)
head, tail = path.split(name)
if not tail:
head, tail = path.split(head)
while head and tail:
try:
rmdir(head)
except OSError:
break
head, tail = path.split(head)
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…