Der berühmte MIT-Professor Hal Abelson sagte: „Programme müssen geschrieben werden, damit Menschen sie lesen und nur nebenbei, damit Maschinen ausgeführt werden können.“ Obwohl er die Bedeutung des Ausführens von Code absichtlich unterschätzt hat, ist er sich bewusst, dass Programme zwei sehr unterschiedliche Zielgruppen haben. Compiler und Interpreter ignorieren Kommentare und finden alle syntaktisch korrekten Programme gleichermaßen leicht verständlich. Menschliche Leser sind sehr unterschiedlich. Einige Programme sind für uns schwerer zu verstehen als andere, und wir suchen nach Kommentaren, um sie zu verstehen.
Während es viele Ressourcen gibt, die Programmierern helfen, besseren Code zu schreiben – wie Bücher und statische Analyseprogramme –, gibt es nur wenige, um bessere Kommentare zu schreiben. Während es einfach ist, die Quantität der Kommentare in einem Programm zu messen, ist es schwierig, die Qualität zu messen, und die beiden sind nicht unbedingt korreliert. Ein schlechter Kommentar ist schlimmer als gar kein Kommentar. Wie Peter Vogel geschrieben hat:
Kommentare zu schreiben und dann zu pflegen ist ein Aufwand.
Ihr Compiler überprüft Ihre Kommentare nicht, sodass Sie nicht feststellen können, ob die Kommentare korrekt sind.
Auf der anderen Seite wird Ihnen garantiert, dass der Computer genau das tut, was Ihr Code ihm sagt.
Obwohl all diese Punkte wahr sind, wäre es ein Fehler, ins andere Extrem zu gehen und niemals Kommentare zu schreiben. Hier sind einige Regeln, die Ihnen helfen, eine glückliche Mitte zu erreichen:
Regel 1: Kommentare sollten den Code nicht duplizieren.
Regel 2: Gute Kommentare entschuldigen keinen unklaren Code.
Regel 3: Wenn Sie keinen klaren Kommentar schreiben können, liegt möglicherweise ein Problem mit dem Code vor.
Regel 4: Kommentare sollten Verwirrung zerstreuen, nicht verursachen.
Regel 5: Erklären Sie unidiomatischen Code in Kommentaren.
Regel 6: Stellen Sie Links zur Originalquelle des kopierten Codes bereit.
Regel 7: Fügen Sie Links zu externen Referenzen dort hinzu, wo sie am hilfreichsten sind.
Regel 8: Fügen Sie Kommentare hinzu, wenn Sie Fehler beheben.
Regel 9: Verwenden Sie Kommentare, um unvollständige Implementierungen zu markieren.
Der Rest dieses Artikels erklärt jede dieser Regeln, bietet Beispiele und erklärt, wie und wann sie angewendet werden.
Regel 1: Kommentare sollten den Code nicht duplizieren
Viele junge Programmierer schreiben zu viele Kommentare, weil sie von ihren Einführungslehrern dafür ausgebildet wurden. Ich habe gesehen, wie Studenten in Informatikklassen der Oberstufe zu jeder geschlossenen Klammer einen Kommentar hinzugefügt haben, um anzuzeigen, welcher Block endet: