Die Kunst der Kommentare

Ich bin der Meinung, dass das Kommentieren von Code wichtig ist. Vor allem aber glaube ich, dass Kommentare missverstanden werden. Ich habe neulich getwittert: „Ich höre widersprüchliche Meinungen darüber, ob man Kommentare schreiben sollte oder nicht. Aber ich bekomme Dankesnachrichten von Junior-Entwicklern, weil ich sie schreibe, also mache ich weiter.“ Die Antworten, die ich erhielt, waren vielfältig, aber was mir auffiel, war, dass jeder, der zustimmte, dass das Kommentieren notwendig sei, andere Gründe dafür hatte.

Kommentieren ist eine nuanciertere Sache, als wir ihr zugestehen. Es gibt keine Nomenklatur für das Kommentieren (nicht, dass es sie geben sollte), aber alle Kommentare über einen Kamm zu scheren, ist eine Vereinfachung. Das Beispiel in diesem Comic, das als Antwort getwittert wurde, ist wahr

Hier liegt meiner Meinung nach ein Großteil der Missverständnisse über Kommentare. Das Buch Clean Code von Robert C. Martin spricht darüber: dass Kommentare nicht notwendig sein sollten, weil Code selbsterklärend sein sollte. Dass, wenn man ein Kommentar für notwendig hält, man es besser schreiben sollte. Ich stimme dem teilweise zu und teilweise nicht. Beim Schreiben eines Kommentars kann man oft Dinge finden, die besser geschrieben werden könnten, aber es ist kein Entweder-Oder. Ich könnte den Code immer noch besser selbsterklärend schreiben und zusätzlich ein Kommentar verfassen, aus folgendem Grund

Code kann beschreiben wie, aber er kann nicht erklären warum.

Das ist kein neues Konzept, aber es ist ein häufiges Thema, das mir bei hilfreichen Kommentaren auffällt, auf die ich gestoßen bin. Die Fähigkeit, etwas zu kommunizieren, was der Code nicht oder nicht prägnant kann.

All das gesagt, es gibt nicht nur einen richtigen Weg oder einen Grund, ein Kommentar zu schreiben. Um besser zu lernen, tauchen wir in einige der vielen nützlichen Arten von Kommentaren ein, die alle einen anderen Zweck erfüllen können, gefolgt von Mustern, die wir vermeiden sollten.

Gute Kommentare

Was ist das Warum

Viele Beispiele für gute Kommentare können unter dieser Kategorie zusammengefasst werden. Code erklärt, was Sie möchten, dass der Computer ausführt. Man spricht von deklarativem Code, weil er die Logik präzise beschreibt, aber nicht alle Schritte wie ein Rezept auflistet. Er überlässt die schwere Arbeit dem Computer. Wir könnten auch unsere Kommentare etwas deklarativer gestalten

/*
  We had to write this function because the browser 
  interprets that everything is a box
*/

Dies beschreibt nicht, was der Code darunter tun wird. Es beschreibt nicht die Aktionen, die er ausführen wird. Aber wenn Sie einen eleganteren Weg gefunden haben, diese Funktion neu zu schreiben, könnten Sie sich sicher fühlen, dies zu tun, da Ihr Code wahrscheinlich die Lösung für dasselbe Problem auf andere Weise ist.

Daher ist weniger Wartungsaufwand erforderlich (darauf gehen wir später noch genauer ein). Wenn Sie einen besseren Weg gefunden hätten, dies zu schreiben, müssten Sie das Kommentar wahrscheinlich nicht neu schreiben. Sie könnten auch schnell verstehen, ob Sie einen anderen Teil des Codes neu schreiben könnten, um diese Funktion überflüssig zu machen, ohne lange Zeit mit dem Parsen aller Schritte zur Vollständigkeit zu verbringen.

Etwas klären, das für normale Menschen nicht lesbar ist

Wenn Sie sich eine lange Regex-Zeile ansehen, können Sie dann sofort erkennen, was vor sich geht? Wenn ja, gehören Sie zur Minderheit, und selbst wenn Sie es im Moment können, könnten Sie es nächstes Jahr nicht mehr. Was ist mit Browser-Hacks? Haben Sie das jemals in Ihrem Code gesehen?

.selector { [;property: value;]; }

was ist mit

var isFF = /a/[-1]=='a';

Das erste zielt auf Chrome ≤ 28, Safari ≤ 7, Opera ≥ 14, das zweite auf Firefox Versionen 2-3. Ich habe Code geschrieben, der so etwas braucht. Um zu vermeiden, dass ein anderer Wartender oder ein zukünftiges Ich annimmt, ich hätte Salvia genommen, bevor ich zur Arbeit gegangen bin, ist es großartig, den Leuten zu sagen, wofür das ist. Insbesondere zur Vorbereitung auf eine Zeit, in der wir diesen Browser nicht mehr unterstützen müssen, oder der Browser-Bug behoben ist und wir ihn entfernen können.

Was Ihnen klar und lesbar ist, ist nicht unbedingt für andere klar

Wer ist schlau? Wir sind es! Wer schreibt sauberen Code? Wir tun es! Wir müssen nicht kommentieren, seht, wie klar es ist. Das Problem mit dieser Denkweise ist, dass wir alle tiefere Kenntnisse in verschiedenen Bereichen haben. In kleinen Teams, in denen die Fähigkeiten und das Fachwissen der Leute eher ein Kreis als ein Venn-Diagramm sind, ist dies weniger ein Problem als in großen Gruppen, die Teams wechseln oder häufig Junior-Entwickler oder Praktikanten bekommen. Aber ich würde wahrscheinlich immer noch Raum für diese Neulinge oder für ein zukünftiges Ich lassen. In größeren Teams mit Junior-Ingenieuren oder einfach Ingenieuren aller Hintergründe sagen uns die Leute vielleicht nicht offen, dass sie uns zum Kommentieren brauchen, aber viele dieser Leute werden sich auch dankbar äußern, wenn Sie es tun.

Kommentare wie Buchkapitel

Wenn dieser Artikel als ein einziger Block geschrieben wäre, anstatt in Abschnitte mit Weißraum und kleineren Überschriften unterteilt zu sein, wäre er schwerer zu überfliegen. Vielleicht trifft nicht alles, was ich sage, auf Sie zu. Das Kommentieren von Abschnitten oder Teilen ermöglicht es den Leuten, zu dem Teil zu springen, der für sie am relevantesten ist. Aber ach! Sagen Sie. Wir haben jetzt funktionale Programmierung, Imports und Module dafür.

Das stimmt! Wir zerlegen Dinge in kleinere Teile, damit sie handlicher sind, und Gott sei Dank dafür. Aber selbst in kleineren Codeabschnitten werden Sie zwangsläufig auf ein Stück stoßen, das etwas länger sein muss. Die Möglichkeit, schnell zu erfassen, was relevant ist oder ein Etikett für einen Bereich, der etwas anders ist, kann die Produktivität steigern.

Ein Leitfaden, um die Logik während des Schreibens des Codes aufrechtzuerhalten

Das ist eine interessante Sache! Das sind nicht die Kommentare, die man behält, und daher auch im Abschnitt „schlechte Muster“ zu finden wären. Oftmals, wenn ich an einem größeren Projekt mit vielen beweglichen Teilen arbeite, ist es extrem hilfreich, Dinge in die Aktionen zu zerlegen, die ich ausführen werde. Dies kann so aussehen:

// get the request from the server and give an error if it failed
// do x thing with that request
// format the data like so

Dann kann ich mich leicht auf eine Sache konzentrieren. Aber wenn diese Kommentare im Code verbleiben, können sie später störend zu lesen sein. Sie sind beim Schreiben sehr nützlich, aber sobald Sie fertig sind, können sie lediglich eine Duplizierung dessen sein, was der Code tut, und zwingen den Leser, dasselbe zweimal auf zwei verschiedene Arten zu lesen. Sie machen das Schreiben zwar nicht weniger wertvoll.

Mein Vorschlag für die perfekte Welt wäre, diese Kommentare während des Schreibens zu verwenden und sie dann später zu überprüfen. Wenn Sie sie löschen, könnten Sie fragen: „Macht das das auf die eleganteste und lesbarste Weise möglich?“ „Gibt es ein anderes Kommentar, das ich anstelle dieses schreiben könnte, um zu erklären, warum dies notwendig ist?“ „Was wäre das Nützlichste, was ich meinem zukünftigen Ich oder anderen mitteilen könnte?“

Das ist in Ordnung zum Refaktorieren

Hatten Sie jemals eine sehr aggressive Produkt-Deadline? Vielleicht haben Sie eine Funktion implementiert, mit der Sie selbst nicht einverstanden waren, oder man sagte Ihnen, sie sei „temporär“ und „nur ein AB-Test, also spielt es keine Rolle“. *Horrormusik einsetzen* … und dann lebte sie weiter … für immer…

So peinlich es auch sein mag, Kommentare wie diese zu schreiben

// this isn't my best work, we had to get it in by the deadline

ist ziemlich hilfreich. Als Wartender spare ich, wenn ich auf Kommentare wie diese stoße, Unmengen an Zeit, um herauszufinden, was mit dieser Person los ist, und mir Wege vorzustellen, wie ich ihren Morgenweg sabotieren könnte. Ich höre sofort auf, darüber nachzudenken, welche Teile dieses Codes ich erhalten sollte, und konzentriere mich stattdessen darauf, was refaktorisiert werden kann. Die einzige Warnung, die ich geben werde, ist, zu versuchen, diese Art des Codierens nicht zu Ihrem Rückgriff zu machen (darüber werden wir weiter unten im Detail sprechen).

Kommentieren als Lehrmittel

Sind Sie eine PHP-Werkstatt, die gerade einen Kunden bekommen hat, der ganz Ruby ist? Vielleicht ist es Standard-Ruby, aber Ihr Team ist leicht überfordert. Schreiben Sie einen Tutorial für jemanden? Dies sind die begrenzten Beispiele, wann das Aufschreiben des Wie hilfreich sein kann. Die Person lernt buchstäblich im Moment und kann vielleicht nicht einfach ableiten, was es tut, weil sie es noch nie zuvor in ihrem Leben gesehen hat. Kommentieren Sie diesen Mist. Lernen ist demütigend genug, ohne dass sie Sie laut fragen müssen, was sie leichter lernen könnten.

Ich habe StackOverflow benutzt, was das Zeug hält

Haben Sie gerade einen ganzen Codeblock von Stack Overflow kopiert und für Ihre Bedürfnisse angepasst? Das ist keine gute Praxis, aber wir waren alle schon mal dort. Etwas, das ich getan habe und das mir in der Vergangenheit geholfen hat, ist, den Link zum Beitrag dort einzufügen, wo ich ihn gefunden habe. Aber! Dann bekommen wir keine Anerkennung für diesen Code! Könnten Sie sagen. Sie optimieren für die falsche Sache, wäre meine Antwort.

Unvermeidlich haben die Leute unterschiedliche Programmierstile und der Autor der Lösung hat ein Problem anders gelöst, als Sie es tun würden, wenn Sie das Gebiet tiefer kennen würden. Warum ist das wichtig? Weil Sie später vielleicht schlauer sind. Sie könnten in diesem Bereich aufsteigen und dann weniger Zeit damit verbringen, sich den Kopf darüber zu zerbrechen, warum Sie es so geschrieben haben, oder aus dem Ansatz des anderen zu lernen. Außerdem können Sie jederzeit zum Beitrag zurückkehren und sehen, ob neue Antworten eingegangen sind, die mehr Licht auf das Thema werfen. Es könnte sogar eine andere, bessere Antwort später geben.

Schlechte Kommentare

Das Schreiben von Kommentaren hat manchmal einen schlechten Ruf, und das liegt daran, dass es tatsächlich schlechte Kommentare gibt. Sprechen wir über einige Dinge, die Sie beim Schreiben vermeiden sollten.

Sie sagen nur, was es bereits tut

John Papa hat den treffenden Witz gemacht, dass dies

// if foo equals bar ...
If (foo === bar) { 

} // end if

ein großes Ärgernis ist. Warum? Weil man tatsächlich alles zweimal auf zwei verschiedene Arten liest. Es liefert keine zusätzlichen Informationen, sondern zwingt dazu, Dinge in zwei verschiedenen Formaten zu verarbeiten, was eher eine mentale Belastung als hilfreich ist. Wir alle haben Kommentare wie diesen geschrieben. Vielleicht, weil wir ihn selbst nicht gut genug verstanden haben oder weil wir uns übermäßig Sorgen machten, ihn später zu lesen. Aus welchem Grund auch immer, es ist immer gut, einen Schritt zurückzutreten und zu versuchen, den Code und das Kommentar aus der Perspektive von jemandem zu betrachten, der ihn liest, anstatt von Ihnen als Autor, wenn Sie können.

Es wurde nicht gepflegt

Schlechte Dokumentation kann schlimmer sein als keine Dokumentation. Es gibt nichts Frustrierenderes, als auf einen Codeblock zu stoßen, in dem das Kommentar etwas völlig anderes sagt als das, was darunter steht. Schlimmer als Zeitverschwendung, es ist irreführend.

Eine Lösung dafür ist sicherzustellen, dass Sie bei der Aktualisierung von Code auch die Kommentare pflegen. Und sicherlich macht *weniger* und nur aussagekräftigere Kommentare diese Instandhaltung weniger mühsam. Aber Kommentare zu schreiben und zu pflegen ist Teil der Arbeit eines Ingenieurs. Das Kommentar ist in Ihrem Code, es ist Ihre Aufgabe, daran zu arbeiten, auch wenn es bedeutet, es zu löschen.

Wenn Ihre Kommentare von vornherein von guter Qualität sind und das Warum und nicht das Wie erklären, stellen Sie möglicherweise fest, dass sich dieses Problem von selbst löst. Wenn ich zum Beispiel schreibe

// we need to FLIP this animation to be more performant in every browser

und diesen Code später refaktorisiere, um von `getBoundingClientRect()` zu `getBBox()` zu wechseln, gilt das Kommentar immer noch. Die Funktion existiert aus demselben Grund, aber die Details des Wie haben sich geändert.

Man hätte einen besseren Namen verwenden können

Ich habe definitiv Leute gesehen, die Code schreiben (oder es selbst getan haben), bei dem die Variablennamen oder Funktionsnamen einstellig sind, und dann das Ding kommentieren. Das ist eine Verschwendung. Wir hassen alle Tippen, aber wenn Sie einen Variablennamen oder eine Funktion wiederholt verwenden, möchte ich nicht das ganze Dokument nach oben scannen, wo Sie erklärt haben, was der Name selbst tun könnte. Ich verstehe, Benennung ist schwer. Aber einige Kommentare ersetzen etwas, das leicht präziser geschrieben werden könnte.

Die Kommentare sind eine Entschuldigung dafür, den Code nicht besser geschrieben zu haben

Das ist der Kern des Problems für viele Leute. Wenn Sie unordentlichen Code schreiben und sich auf Ihre Kommentare verlassen, um ihn zu verdeutlichen, bedeutet dies, dass die Kommentare Ihre Programmierung behindern. Das ist eine Situation, bei der das Pferd vor dem Wagen gespannt wird. Leider ist es selbst für den Autor nicht so einfach zu bestimmen, was was ist.

Wir belügen uns auf vielfältige Weise. Wir könnten die Zeit mit dem Schreiben eines Kommentars verbringen, die besser damit verbracht werden könnte, den Code von vornherein sauberer zu machen. Wir könnten uns auch sagen, dass wir unseren Code nicht kommentieren müssen, weil unser Code gut geschrieben ist, auch wenn andere Leute vielleicht nicht zustimmen.

Es gibt auf beiden Seiten faule Krücken. Tun Sie einfach Ihr Bestes. Versuchen Sie, sich nicht nur auf eine korrekte Methode zu verlassen, sondern schreiben Sie Ihren Code und lesen Sie ihn dann. Versuchen Sie, sich sowohl als Autor als auch als Wartender vorzustellen oder wie dieser Code für ein jüngeres Ich aussehen könnte. Welche Informationen bräuchten Sie, um so produktiv wie möglich zu sein?

---

Die Leute neigen in letzter Zeit dazu, sich auf die eine oder andere Seite von „ob man Kommentare schreiben sollte“ zu stellen, aber ich würde argumentieren, dass diese Unterhaltung nicht nuanciert genug ist. Hoffentlich öffnet die Diskussion über die Art und Weise, wie man aussagekräftige Kommentare schreibt, die Lücke.

Dennoch kann es viel zum Nachdenken sein. Haha, verstehen Sie? Wie auch immer, ich hinterlasse Ihnen etwas (besseren) Humor. Vor einiger Zeit gab es einen Stack Overflow-Beitrag über die besten Kommentare, die Leute geschrieben oder gesehen haben. Hier können Sie definitiv einige Zeit verschwenden. Ziemlich lustige Sachen.