Leitfaden zum Schreiben guter Code-Kommentare

• Die Rolle von Code-Kommentaren:

  • Code-Kommentare gehen über die Erklärung dessen hinaus, „was der selbst geschriebene Code tut“, und dokumentieren auch Überlegungen wie Designentscheidungen und Trade-offs
  • Dadurch wird erklärt, „was der Autor des Codes getan hat und warum er es so gemacht hat“
  • Code-Kommentare helfen dabei, den Kontext von Entscheidungen zu teilen, die während des früheren Entwicklungsprozesses getroffen wurden
  • So werden Informationen über den Code vermittelt, die sich nur schwer allein im Code ausdrücken lassen

• Die Bedeutung von Code-Kommentaren:

  • Inline-Kommentare vor komplexem Code sparen anderen Entwicklern, die den Code später lesen, Zeit
  • Je weiter sich ein Projekt entwickelt, desto hilfreicher ist es für andere Entwickler, den Kontext früherer Code-Entscheidungen festzuhalten
  • Wenn der Code komplex ist, sollte es zumindest einen einzeiligen Inline-Kommentar davor geben
  • Es gibt Grenzen dabei, allein mit Code vielfältige Informationen zu vermitteln, einschließlich des Kontexts von Code-Entscheidungen

• Wie man gute Code-Kommentare schreibt:

  1. Kurz und prägnant schreiben
     • Kommentare nur dann schreiben, wenn sie wirklich nötig sind, und nur die wesentlichen Informationen aufnehmen
       • wenn der Code unvermeidlich komplex ist
       • wenn zur Erhöhung der Genauigkeit zusätzliche Details ergänzt werden
       • wenn Kontext fehlt (z. B. bei der Nutzung von Code aus anderen Repositories oder Paketen)
     • Verwirrung und Mehrdeutigkeit in Kommentaren reduzieren und nützlichen Kontext sowie relevante Informationen liefern
  2. TODO-/FIXME-Kommentare verwenden
     • TODO-/FIXME-Kommentare sind eine Möglichkeit, anzuzeigen, dass die Arbeit an einem bestimmten Teil des Codes noch nicht abgeschlossen ist oder korrigiert werden muss
     • Vor einer Funktion kann zum Beispiel so etwas stehen wie: „TODO: XX-Funktion muss hinzugefügt werden“
     • Wenn man beim Schreiben des Codes denkt: „Diesen Teil sollte ich mir später noch einmal ansehen“ oder „Diese Funktion muss später noch entwickelt werden“, kann man diese Methode nutzen, um solche Punkte festzuhalten und nachzuverfolgen
     • Nützliche Extension: TODO Highlight
  3. Den Code nicht mit Kommentaren rechtfertigen
     • Statt fehlerhaften oder unklaren Code mit Kommentaren zu entschuldigen, sollte man den Code lieber neu schreiben
     • Manche Stellen müssen durch Kommentare erklärt werden, andere sollten ohne Kommentare allein durch „den Code selbst“ sprechen
  4. KI nutzen
     • Mit einem KI-Kommentargenerator lassen sich Kommentare in einem konsistenten Format nach bestimmten Standards erstellen
     • So kann die Konsistenz der Kommentare im gesamten Projekt gewahrt und die Lesbarkeit des Codes verbessert werden
     • Nützlicher KI-Kommentargenerator: Readable

[penza1]

Wenn es so wirkt, als bräuchte der Code einen Kommentar,
sollte man vielleicht erst einmal überlegen, ob nicht mit dem Code selbst etwas nicht stimmt.

Kommentare, die nicht zusammen mit dem Code lebendig bleiben und dieselbe Funktion mittragen, können zukünftige Entwickler oder auch einen selbst eher verwirren.

Selbst wenn der Kontext aus der Vergangenheit heute nicht mehr relevant ist oder sogar Fehler verursacht hat,
kann genau dieser alte Kontext dazu führen, dass man bei aktuellen Änderungen zögert oder Umwege geht, um es in einer anderen Struktur zu lösen,
und dadurch noch mehr Fehler provoziert ...

Meiner Erfahrung nach gibt es gar nicht so viele Kommentare, aus denen man wirklich erkennen kann, warum etwas damals richtig war, heute aber falsch ist....

[ironlung]

Vielen Dank, dass Sie Ihre wertvolle Meinung geteilt haben. Wenn ich über Ihre Anmerkung nachdenke, scheint es mir, dass wir uns auch für die Weiterentwicklung des Codes sorgfältig fragen sollten, ob Kommentare wirklich notwendig sind. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

Wenn ich mir das anschaue, bemühe ich mich auch, Kommentare nicht übermäßig zu verwenden.

[ironlung]

Vielen Dank fürs Teilen des tollen Videos! :)

[iamchanii]

Egal, wie gut eine Straße ausgebaut ist, Wegweiser sind meiner Meinung nach trotzdem unverzichtbar. Deshalb versuche ich mir in letzter Zeit anzugewöhnen, Kommentare zu schreiben.

[ironlung]

Vielen Dank, dass Sie Ihre Einblicke in den Kommentaren geteilt haben. Wenn ich über Ihren Hinweis nachdenke, wird mir wieder bewusst, dass auch Kommentare ein wichtiger Teil des technischen Schreibens sind und es sich lohnt, die grundlegenden Schreibprinzipien noch einmal zu überdenken. :)

[balak]

Ich denke, am besten ist es, Code so zu schreiben, dass er auch ohne Kommentare verständlich ist.

[ironlung]

Ja, ich denke auch, dass es zuerst darauf ankommt, die Grundlagen solide umzusetzen. Danke für den Kommentar. :)