Jun 22, 2019

the code is documentation enough - oder?

Kommentare im Code, das ist für sehr viele Menschen, die schon einmal ein paar Zeilen in der Hand hatten, nicht unbedingt etwas Neues. Ich als fortgeschrittene Anfängerin, wie ich mich selbst in diesem Sinne einfach mal bezeichnen möchte, habe auch relativ früh begonnen, damit Bekanntschaft zu machen. Daher will ich darüber schreiben, wie mein Verhältnis zu Codekommentaren war, ist und vielleicht auch sein wird.
Tatsächlich bin ich nämlich nicht der Meinung, dass Code pauschal selbsterklärend ist. Ich höre in diesem Bereich oft "the code is documentation enough" und als jemand, der mittlerweile weiß, wie viele Gedanken hinter fünf Zeilen stehen können, möchte ich eigentlich dazu motiviert werden, diese Gedanken auch nachzuvollziehen, sehr gerne auch, wenn es sich dabei um meine eigenen, vergangenen Gedanken handelt.

Beginnen wir erst einmal bei meinen Erfahrungen mit Programmierung. Im Informatik-Unterricht hatte ich als Sprache Delphi/Object Pascal und habe da meine ersten Erfahrungen gemacht, die ich aber gerne als 0. Erfahrungen bezeichne. Wir sind im Endeffekt nicht über Schleifen hinausgekommen und vieles war auch (teilweise mit Bugs behafteten) Code vom Buch abschreiben und im Programm schauen, was passiert. Irgendwann fand ich es total toll, die Farbe meines Programms zu ändern und so hatte bald alles, was ich programmierte, einen Dark Mode. Ich habe den Dark Mode also vor macOS implementiert. Aber viel mit Code-Kommentaren war da nicht. Ich weiß nicht mehr viel von Delphi, erst recht nicht, wie ich Kommentare schreibe. Zugegeben, das war auch nicht unbedingt nötig. Dass wir in unsere Schleifen lieber ein break-Statement packten, wussten wir aufgrund Endlosschleifen und Versuchen mit einem Task-Manager, die loszuwerden, auch. Keine Kommentare, keine Dokumentation, im Zweifelsfall stand eh alles Notwendige im Buch.

Dann belegte ich vor einem knappen Dreiviertel-Jahr einen Python-Kurs an der Uni. Im Zweifelsfall etwas auszukommentieren kannte ich bereits von LaTeX und war für mich ein bekanntes Verfahren, um den Bereich eines Fehlers einzuschränken. In Python war das sogar noch einfacher als in LaTeX.
Irgendwann verwendete ich dann Code-Kommentare als wirkliche Dokumentation, aber nicht für mich, sondern eher, damit andere Menschen meine Abgaben verstehen. Eigentlich war es nämlich so, dass wir unsere Lösungen in der Übung einem der Übungsgruppenleiter vorstellten. Allerdings hatte ich da zu Anfang wenig, zu Ende immer mehr Praktikumstage am Tag der Übung. Also konnte ich niemandem mehr erklären, was ich tue, und musste Code-Kommentare schreiben, damit die Menschen, die später meinen Code sehen, verstehen, was ich tue und was ich sonst erklärt hatte. Das waren dann in der Regel solche Dinge wie "plot for all functions" oder "dictionary for all ingredients of pizza", also eigentlich etwas, was selbsterklärend ist. Das sind vermutlich die Gründe, aus denen auch solche Memes entstehen wie "99% of all code comments" und wir haben ein Bild einer Katze, auf der "cat" steht. Etwa so:

Code-Kommentare als Beschreibung "Cat" mit einer Katze

Allerdings hat Code von mir eine weitere Eigenschaft. Meine Namen von Variablen, Klassen, Funktionen und so ziemlich allem ist nicht unbedingt aussagekräftig. Ich werde ganz gerne mal kreativ und finde mich lustig. Das hat zur Folge, dass in einem Programm, in dem irgendwas mit \(\pi\) passiert, das von mir geschrieben wurde, überdurchschnittlich oft die Wörter "pie", "lie" und "cake" vorkommen. Ich habe auch mal ein Programm zum Üben von Vokabeln geschrieben und es Voq genannt. Hätte ich allen Funktionen und Klassen irgendwas Klingonisches zugeordnet, wäre es ohne erklärende Kommentare schwierig geworden. Bei einem Programm, das mit der Brownschen Molekularbewegung zu tun hat, taucht überdurchschnittlich das Wort "Brownie" auf. Genauso würde in einem Programm zur Caesar-Verschlüsselung überdurchschnittlich oft das Wort "Salad" vorkommen. Ich mag Wortspiele, solche Situationen erheitern mich. Ich bin die Person, die so was wie "char izard", "char mander" oder "int entionally" schreibt. Code darf und soll für mich irgendwo auch kreativ sein und Spaß machen. Deswegen sagte jemand auch mal in meiner Gegenwart "Manche Menschen nennen es "main", andere Menschen nennen diese Funktion "doallthestuff"". Das ist dann auch tatsächlich eher privater Code.
Wenn ich diesen Code allerdings drei Wochen später anfasse und ich nicht weiß, wofür meine Cakes, Pies, Klingons, Brownies, Salads und Charmanders da sind und was sie eigentlich tun, ich also erstmal im besten Fall herausfinde, was ich warum getan habe, im schlechtesten Fall alles schließe, ist das nicht so erstrebenswert. Deswegen begann ich vor einiger Zeit, für mich, Code-Kommentare nicht mehr als offensichtlich zu gestalten.

Mittlerweile schreibe ich mir da Erklärungen wie "Information in dictionary is splitted in key -> value, value is a tuple, but user check is for all" rein, also beispielsweise Informationen, wie etwas gespeichert ist. Ich hatte auch mal einen Aufruf eines Strings mit randomdictionary[0][1][1][1]. Wenn ich also Listen in Listen und Dictionaries habe, dann ist es vielleicht auch nicht die beste Idee, diese Art der Speicherung zu wählen. Aber was will ich denn auch großartig machen, wenn ich ein Dictionary in einer .txt speichern soll, nee? Bitte widersteht an der Stelle der Versuchung, mir in einem sozialen Netzwerk eurer Wahl zu schreiben, wie ich das anders und "besser" machen soll, danke schön. Aber in solchen Fällen habe ich ein Problem, wenn ich nicht irgendwie dokumentiere, was genau ich warum tue.
Seit kurzem versuche ich mich an kleineren Dingen mit SQLite. Meine bisherigen Berührungspunkte mit SQL sind gering. Somit ist quasi für mich sehr vieles neu, sehr vieles ungewohnt, sehr vieles auf den ersten Blick nicht ganz so verständlich und das ist total in Ordnung. Also schreibe ich mir in meinen Code, was ich genau warum tue, was was tut, warum ich genau dieses Konzept gewählt habe oder wählen musste. Es sind quasi "Nice to have"-Informationen. Glücklicherweise weiß ich auch gleichzeitig, wie ich denke und welche Informationen mir persönlich weiterhelfen.

Seitdem habe ich tatsächlich auch wieder eine Programmieraufgabe abgegeben. Wenn ich weiß, welche Person das liest und wie meine Erkärungen sonst so sind, kommt da auch mal was wie "if (n > depth) { // I don't want to kill my RAM with endless recursion" raus. Einfach, weil ich mir sicher bin, dass das in diesem Moment vollkommen in Ordnung ist. Abgesehen davon ist es für mich auch irgendwie lustig und wenn ich schon im Code selbst lustig bin, dann kann ich das auch in den Kommentaren sein, wenn ich das möchte. Es kommt immer ein wenig darauf an, wer das lesen und verstehen soll. In erster Linie bin das ich. Wenn ich meinen Code mit anderen Menschen teile, weil sie zum Beispiel meinen Code im Rahmen von einem Kurs bewerten, dann ist das entweder mündlich oder ich weiß grob, wie ich es diesen Menschen erklären würde und kippe es so in die Kommentare.

Was ich sehr schade finde, ist, dass bisher kein Programmierkurs mich darauf hingewiesen hat, wie wichtig Code-Kommentare sein können und dass diese Art der Dokumentation oftmals hinten runter fällt. Klar, Programmieraufgaben, die man wöchentlich meistens in einem durch programmiert, brauchen nicht unbedingt Kommentare, weil das, was getan wurde, zeitlich noch sehr frisch ist. Ich habe in einem Kurs gelernt, dass es in Python offenbar ganz cool ist, dass Kommentare in einer eigenen Zeile stehen.
Von Tools wie Doxygen hörte oder eher las ich erst im Buch "C im 21. Jahrhundert". Ich kann verstehen, dass das nicht unbedingt in (Anfänger-)Kursen behandelt wird. Das würde ich durchaus auch als weiter fortgeschritten bezeichnen. Aber wie schreibe ich gute Codekommentare? Wie vermeide ich es, eine Funktion "cat" zu schreiben und den Kommentar dazu "cute cat" zu nennen? Denn eigentlich ist der Code nicht Dokumentation genug, gerade für Menschen, die noch neu in dieser Welt sind. Dokumentation kann Erklärung und Vereinfachung sein und ist somit für mich ein mächtiges Tool, um meinem Kopf auf die Sprünge zu helfen, meine eigenen Gedanken zu rekonstruieren.