Why Not-Kommentare

• Warum nicht „Warum nicht“-Kommentare? Nicht warum „keine Kommentare“
  • „Warum hinterlasst ihr keine Kommentare dazu, warum etwas nicht funktioniert hat? Ich frage nicht nach dem Grund, warum ihr keine Kommentare geschrieben habt.“

Why Not Comments

• Code wird in einer strukturierten Maschinensprache geschrieben, Kommentare hingegen in einer ausdrucksstarken menschlichen Sprache
• Gemeint ist: Kommentiere nicht das „Was“, sondern packe so viele Informationen wie möglich in Bezeichner
• In letzter Zeit wird sogar behauptet, man solle auch das „Warum“ nicht in Kommentare schreiben, sondern in LongFunctionNames oder Namen von Testfällen packen
• Eine „selbstdokumentierende“ Codebasis fügt Dokumentation über Bezeichner hinzu

Ein aktuelles Beispiel

• Ein Beispiel aus Logic for Programmers
• Es trat das Problem auf, dass der epub-Build mathematische Symbole (\forall) nicht in Zeichen (∀) umwandeln konnte
• Es wurde ein Skript geschrieben, das Tokens in mathematischen Zeichenketten manuell durch Unicode ersetzt
• Es wurde so geschrieben, dass 16 mathematische Symbole jeweils ersetzt werden, was jedoch ineffizient ist
• Mit einem einfachen Kommentar wurde das Problem gelöst
  • „Es wird zwar für jede Zeichenkette 16-mal wiederholt, aber das Buch hat derzeit nur 25 mathematische Zeichenketten und die meisten sind kürzer als 5 Zeichen, also ist es immer noch schnell genug.“

Warum man Kommentare schreiben sollte

• Warum man Kommentare schreiben sollte, auch wenn langsamer Code aktuell keine Probleme verursacht
• In Zukunft könnte der Code zum Problem werden
• Kommentare zeigen, dass man sich des Trade-offs bewusst ist
• Wenn man das Projekt später noch einmal ansieht, kann man verstehen, warum man langsamen Code geschrieben hat

Warum Selbstdokumentation nicht möglich ist

• Lange Funktionsnamen wie „RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs“ erklären den Trade-off nicht
• Funktions- und Variablenbezeichner können nur eine Art von Information enthalten
• Es ist auch nicht möglich, Kommentare durch Tests zu ersetzen
• Selbstdokumentation erklärt, was der Code tut, aber negative Information erklärt, was der Code nicht tut

Spekulation am Ende des Newsletters

• Es stellt sich die Frage, ob man „Warum nicht“-Kommentare als kontrafaktische Fälle betrachten kann
• Ist die Abstraktion menschlicher Kommunikation nicht selbstdokumentierbar?
• Kann man Metaphern, Unsicherheit, ethische Behauptungen usw. selbstdokumentierend ausdrücken?

---

Zusammenfassung von GN⁺

• Dieser Artikel behandelt die Bedeutung von Code-Kommentaren und ihre Grenzen
• Kommentare machen Trade-offs im Code klarer und erleichtern zukünftige Wartung
• Er betont die Grenzen von Selbstdokumentation und die Notwendigkeit von Kommentaren

[GN⁺]

Hacker-News-Meinungen

• Beim Kommentieren von Code erkläre ich vor allem das „Warum“ und „warum es nicht geht“. Bei komplexem Code ist es auch nützlich, kurz das „Was“ zu erklären.

  • Verpflichtende Kommentare sind ineffizient, und jede Funktion zu kommentieren ist Zeitverschwendung.
  • Auch Kommentare, die von Tools automatisch hinzugefügt werden, sind ineffizient.

• Junior Engineers schreiben Kommentare, die erklären, was der Code tut, Mid-Level Engineers erklären, warum er so geschrieben wurde, und Senior Engineers erklären, warum er nicht anders geschrieben wurde.

• Ich verwende ein Kommentar-Template für Maintainer.

  • „Dieser Code wurde aus <Grund> so geschrieben. Wenn Sie versuchen, ihn zu ändern, und dann feststellen, dass das ein Fehler war, erhöhen Sie bitte für die nächste Person den Zähler: total_hours_wasted_here = n“

• Es ist wichtig, überraschende Stellen im Code zu kommentieren.

  • Wenn ich nicht sicher bin, ob der Code später noch verständlich sein wird, schreibe ich einen Kommentar, der erklärt, „warum es nicht geht“.

• Die Bedeutung von Kommentaren wird betont, besonders wenn man den eigenen Code auch in 5, 10 oder 15 Jahren noch warten muss.

  • Es ist wichtig, Konsistenz mit bestehendem Code zu wahren.

• Es ist gut, Dinge zu kommentieren, die „nicht die naive Lösung“ sind.

  • Ineffizienter Code kann später Probleme verursachen, wenn er geändert wird.

• Es ist gut, Kommentare in lange Funktionsnamen oder Testfallnamen einzubauen.

  • Wenn der Methodenname nicht klar ist, helfen Kommentare.
  • Wenn in der Methodenbeschreibung ein „und“ vorkommt, ist das ein Zeichen dafür, dass die Methode zu viele Dinge tut.

• Es ist auch nützlich, über Debug-Logging Warnungen hinzuzufügen, wenn Eingaben größer sind als die ursprünglich vorgesehenen Design-Beschränkungen.

• Ich bevorzuge es, viele Kommentare und Dokumentationskommentare zu verwenden.

  • Ich kommentiere die einzelnen Schritte einer Anwendung und verfeinere die Kommentare, während ich den Code schreibe.
  • Ich bevorzuge es, alle Funktionen und Variablen zu kommentieren.

• In Code-Reviews schreibe ich Kommentare wie „Ich habe X nicht gemacht, weil Y“, um erwartete Kritik im Voraus zu entkräften.