# Kommentare Kommentare sind ein viel umstrittenes Thema. Jemand sagt, man sollte möglichst ausführlich kommentieren und wieder ein Anderer sagt man sollte gar keine Kommentare schreiben. Robert C. Martin empfiehlt etwas dazwischen. In diesem Blog möchte ich die Regeln ansprechen die beachtet werden sollten wenn Code Kommentiert wird. Eines der häufigsten Probleme mit Kommentare ist, dass sie ihre Aktualität verlieren. Dies geschieht wenn immer Code geändert wird aber dessen Kommentar nicht angepasst wird. Falsche Kommentare sind tatsächlich Gefährlicher als keine Kommentare, da Entwickler auf die Richtigkeit dieser vertrauen. Viele Entwickler tendieren ausserdem dazu, unverständlichen Code mit Kommentaren auszustatten. Es gibt also allerlei Probleme mit Kommentaren: 1. Kommentare können einfach vergessen werden, wenn Code verschoben wird, was sie unverständlich macht 2. Sie können alte Informationen enthalten, die nicht mehr auf den Code zutreffen. 3. Sie können Fehlinformationen enthalten die falsche oder nicht alle Informationen enthalten. 4. Sie können das Erlebnis des Lesers stark beeinträchtigen. Auf einige dieser Punkte will ich genauer eingehen und eine Lösung bieten, wie Kommentare stattdessen eingesetzt werden können. Kommentare sind kein Ersatz für schlechten Code. Wenn einem die Idee kommt die Funktionalität eines Code Blocks in einem Kommentar zu beschreiben wegen der Angst, dass man ansonsten den Code nicht verstehen würde, ist ein grundlegender Fehler passiert. Code sollte selbsterklärend sein. Dies kann durch eine gute [[1. Namensgebung|Namensgebung]] und [[2. Funktionen|Aufteilung der Aufgaben auf eigene Funktionen]] gewährleistet werden. ## Gute Kommentare Die folgende Liste enthält alle Arten von Kommentaren die gut und teilweise sogar nötig sind: ### Juristische Kommentare Es gibt juristische Situationen die einen Kommentar voraussetzen. So muss beispielsweise bei der Verwendung von Lizensiertem Code je nach Lizenz Art die Lizenz und der ursprüngliche Autor im Code erwähnt oder referenziert werden. ### Informierende Kommentare Manchmal ist es hilfreich, wenn kleine informierende Kommentare vorhanden sind. Dies macht dann Sinn, wenn die Absicht des Codes nicht durch eine Änderung der Namen oder Struktur übermittelt werden kann. Es muss jedoch beachtet werden, dass diese schnell verloren gehen oder ihre Aktualität verlieren. Sie müssen also aufwendig gewartet werden und sollten nur selten verwendet werden. ### Erklärungen der Absicht Ist zwar klar, was ein Codeabschnitt macht, jedoch nicht wieso, macht es Sinn, in einem Kommentar seine Absichten zu erklären. ### Klarstellungen Es kann ausserdem Sinn machen, die Bedeutung absurder Argumente oder Rückgabewerte genauer zu beschreiben. ### Warnung vor Konsequenzen Dies wird mit dem Beispiel eines Tests erklärt, welcher sehr viel Zeit und Leistung braucht. Hat man einen solchen Test oder ähnliches sollten zukünftige Entwickler gewarnt werden. ### TODO-Kommentare Einige Entwickler haben die Angewohnheit, unfertige Aufgaben durch einen TODO-Kommentar festzuhalten. Diese sind nicht schlimm, sollten jedoch regelmässig bearbeitet werden damit sie nicht ihre Aktualität verlieren. Mit aktuellen IDEs ist das jedoch kein Problem. ## Schlechte Kommentare Diese Liste wiederum enthält alle Arten von Kommentaren, die unbedingt weggelassen werden sollten: ### Redundante Kommentare Kommentare, die das gleiche Aussagen, das bereits durch den Code gesagt wird oder werden kann, sind redundant und endsprechend nicht nötig. Es macht es viel schwieriger den Code zu lesen und verbraucht Platz. ### Irreführende Kommentare Kommentare die falsche Informationen sollte unter allen Umständen weggelassen werden. Aus diesem Grund ist es auch wichtig, alte Kommentare regelmässig zu überarbeiten. Werden sie das nicht, enthalten sie schnell alte Informationen, die nicht mehr zutreffen und den Entwickler nur verwirren.  ### Geschwätz Alle Kommentare, die keinen Inhaltlichen Wert bieten, sollten weggelassen werden. ### Auskommentierter Code Code sollte niemals auskommentiert werden. Für einen temporären Test kann es gemacht werden. Sobald der Code jedoch eingesetzt wird, darf niemals auskommentierter Code vorhanden sein. ### Zu viele Informationen Erklärende Kommentare sind akzeptabel und sogar empfohlen. Diese sollten jedoch nur die wichtigsten Infos enthalten. Randinformationen sollten immer weggelassen werden, da sie das Lesen und Verstehen nur erschweren.