Kommentare in den Code einfügen: das Gute, das Schlechte und das Hässliche.

Hör auf mich, wenn du das schon mal gehört hast ...

"Guter Code ist selbstdokumentierend."

In mehr als 20 Jahren, in denen ich Code für meinen Lebensunterhalt geschrieben habe, ist dies der eine Satz, den ich am meisten gehört habe.

Es ist ein Klischee.

Und wie viele Klischees hat es einen Kern der Wahrheit. Aber diese Wahrheit wurde so missbraucht, dass die meisten Menschen, die den Satz aussprechen, keine Ahnung haben, was er wirklich bedeutet.

Ist es wahr? Ja .

Bedeutet das, dass Sie Ihren Code niemals kommentieren sollten? Nein .

In diesem Artikel werden wir uns mit dem Guten, dem Schlechten und dem Hässlichen befassen, wenn es darum geht, Ihren Code zu kommentieren.

Für den Anfang gibt es wirklich zwei verschiedene Arten von Codekommentaren. Ich nenne sie Dokumentationskommentare und Klarstellungskommentare .

Kommentare zur Dokumentation

Dokumentationskommentare sind für alle gedacht, die Ihren Quellcode wahrscheinlich verbrauchen, ihn aber wahrscheinlich nicht lesen. Wenn Sie eine Bibliothek oder ein Framework erstellen, das / das andere Entwickler verwenden, benötigen Sie eine API-Dokumentation.

Je weiter Ihre API-Dokumentation vom Quellcode entfernt ist, desto wahrscheinlicher ist es, dass sie im Laufe der Zeit veraltet oder ungenau wird. Eine gute Strategie, um dies zu vermeiden, besteht darin, die Dokumentation direkt in den Code einzubetten und sie dann mit einem Tool zu extrahieren.

Hier ist ein Beispiel für einen Dokumentationskommentar aus einer beliebten JavaScript-Bibliothek namens Lodash.

Wenn Sie diese Kommentare mit ihrer Online-Dokumentation vergleichen, werden Sie feststellen, dass sie genau übereinstimmen.

Wenn Sie Dokumentationskommentare schreiben, sollten Sie sicherstellen, dass diese einem einheitlichen Standard entsprechen und leicht von Inline-Klarstellungskommentaren zu unterscheiden sind, die Sie möglicherweise auch hinzufügen möchten. Einige beliebte und gut unterstützte Standards und Tools umfassen JSDoc für JavaScript, DocFx für dotNet und JavaDoc für Java.

Der Nachteil dieser Art von Kommentaren ist, dass sie Ihren Code für jeden, der aktiv an der Pflege beteiligt ist, sehr "laut" und schwerer lesbar machen können. Die gute Nachricht ist, dass die meisten Code-Editoren das „Falten von Code“ unterstützen, wodurch wir die Kommentare reduzieren können, damit wir uns auf den Code konzentrieren können.

Erläuterungen zur Klarstellung

Erläuterungen zur Klärung richten sich an alle Personen (einschließlich Ihres zukünftigen Selbst), die Ihren Code möglicherweise warten, umgestalten oder erweitern müssen.

Oft ist ein Klarstellungskommentar ein Codegeruch. Es sagt Ihnen, dass Ihr Code zu komplex ist. Sie sollten sich bemühen, Erläuterungen zu entfernen und stattdessen den Code zu vereinfachen, da „guter Code sich selbst dokumentiert“.

Hier ist ein Beispiel für einen schlechten - wenn auch sehr unterhaltsamen - Klarstellungskommentar.

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

Anstatt eine etwas verwirrende Aussage mit einem cleveren Reim zu dekorieren - nicht weniger im Amphibrach-Dimeter -, wäre es für den Autor weitaus besser gewesen, Zeit mit einer Funktion zu verbringen, die das Lesen und Verstehen des Codes selbst erleichtert. Vielleicht eine Funktion namens, removeCurlyBracesaufgerufen von einer anderen Funktion namens sanitizeInput?

Versteh mich nicht falsch, es gibt Zeiten, in denen es gut für die Seele sein kann, ein bisschen Humor zu injizieren, besonders wenn du dich durch eine drückende Arbeitsbelastung schlägst. Wenn Sie jedoch einen lustigen Kommentar schreiben, um schlechten Code auszugleichen, ist die Wahrscheinlichkeit geringer, dass Benutzer den Code später umgestalten und korrigieren.

Wollen Sie wirklich derjenige sein, der dafür verantwortlich ist, allen zukünftigen Programmierern die Freude zu rauben, diesen klugen kleinen Reim zu lesen? Die meisten Programmierer kicherten und gingen weiter und ignorierten den Codegeruch.

Es gibt auch Zeiten, in denen Sie auf einen redundanten Kommentar stoßen. Wenn der Code bereits einfach und offensichtlich ist, müssen Sie keinen Kommentar hinzufügen.

Mach diesen Unsinn nicht:

/*set the value of the age integer to 32*/int age = 32;

Es gibt jedoch Zeiten, in denen unabhängig davon, was Sie mit dem Code selbst tun, ein Kommentar zur Klarstellung immer noch gerechtfertigt ist.

Normalerweise geschieht dies, wenn Sie einer nicht intuitiven Lösung einen Kontext hinzufügen müssen.

Hier ist ein gutes Beispiel von Lodash:

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

Es gibt auch Zeiten, in denen sich nach langem Nachdenken und Experimentieren herausstellt, dass die scheinbar naive Lösung eines Problems tatsächlich die beste ist. In diesen Szenarien ist es fast unvermeidlich, dass ein anderer Codierer denkt, er sei viel schlauer als Sie und mit dem Code herumspielt, nur um festzustellen, dass Ihr Weg der beste Weg war.

Manchmal ist dieser andere Codierer dein zukünftiges Selbst.

In diesen Fällen ist es am besten, allen Zeit und Verlegenheit zu ersparen und einen Kommentar zu hinterlassen.

Der folgende Scheinkommentar fängt dieses Szenario perfekt ein:

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Auch hier geht es mehr darum, lustig als hilfreich zu sein. Aber Sie sollten einen Kommentar hinterlassen, der andere warnt, keine scheinbar offensichtliche „bessere Lösung“ zu verfolgen, wenn Sie dies bereits versucht und abgelehnt haben. Und wenn Sie dies tun, sollte der Kommentar angeben, welche Lösung Sie versucht haben und warum Sie sich dagegen entschieden haben.

Hier ist ein einfaches Beispiel in JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

Das hässliche

Wir haben uns also das Gute und das Schlechte angesehen, aber was ist mit dem Hässlichen?

Leider gibt es in jedem Job Zeiten, in denen Sie frustriert sind und wenn Sie Code für Ihren Lebensunterhalt schreiben, kann es verlockend sein, diese Frustration in Codekommentaren abzulassen.

Wenn Sie mit genügend Codebasen arbeiten, werden Sie auf Kommentare stoßen, die von zynisch und deprimierend bis dunkel und gemein reichen.

Dinge wie das scheinbar harmlose…

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

… Auf den Punkt gebracht

/* Class used to workaround Richard being a f***ing idiot*/

These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

Don't do this.

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.