„Kommentieren Sie schlechten Code nicht – schreiben Sie ihn um.“
(Brian W. Kernighan und P.J. Plaugher)
Kommentare können beides sein, hilfreich und hinderlich:
- hinderlich, wenn Sie überholt sind und Fehlinformationen liefern
- störend, wenn Sie zu lang sind und unnötig
- hilfreich, wenn Sie wohlplatziert sind
Der Einsatz von Kommentaren „soll unsere Unfähigkeit ausgleich, uns in unserem Code klar auszudrücken“(S.85). Bevor man einem Kommentar schreibt, sollte man vorher überlegen, ob der Code nicht noch ausdrucksstarker geschrieben werden könnte.
Kommentare sind also nicht als positiv anzusehen.
Das liegt besonders darin, dass sich der Code zwar weiterentwickelt, aber die Kommentare auf der Strecke bleiben, weil Sie z.B. von der IDE versteckt werden.
Die einzige Quelle für genaue und aktuelle Informationen ist der Code selbst.
Bsp: Was ist einfacher zu verstehen?
//Check if it is working time
if($day < 6 && $day > 0 && $time <= 18 && $time >= 9){
//oder
if(isWorkingTime()){
Gute Kommentare
- Juristische Kommentare: Copyright und Autoren-Vermerke am Anfang von Quelldateien. Sie sollten keine Lizenz enthalten, sondern nur auf diese verlinken. Wird durch IDEs ausgeblendet.
- Informierende Kommentare: z.B. bei regulären Ausdrücken, die kompliziert werden können
- Absichtserklärung des Programmierers: Bei interessanten Entscheidungen und Erklärungen der Logik sind Kommentare angebracht, z.B. wenn eine Sortierung bestimmte Objekte bevorzugt
- Warnung vor Konsequenzen: z.B: wenn die Ausführung eines Test-Cases zu lange dauert, sollte dies vermerkt werden. Solche Test-Cases sollten mit @ignore gekennzeichnet werden.
- TODO Kommentare: sind sinnvoll, aber keine Entschuldigung für schlechten Code
- Betonung: besonders wichtige, aber unbedeutend aussehenden Zeilen, sollten kommentiert sein, damit Sie nicht entfernt werden.
Schlechte Kommentare
- Geraune: „Jeder Kommentar, der Sie zwingt, in anderen Modulen nach einer Bedeutung zu suchen…ist die Bits nicht wert, die er konsumiert.“ (S.93)
- Redundante Kommentare/ Geschwätz: Bsp. Funktions-Kommentare, die den Code vorlesen und dabei noch Informationen weglassen sind redundant und sogar schädlich. Außerdem machen Sie den Code unübersichtlich. Der Leser wird verleitet die Kommentare zu überlesen.
- Irreführende/ falsche Kommentare
- vorgeschriebene Kommentare: Wenn vorgeschrieben ist, dass jede Funktion und Variable einen Kommentar haben muss, entstehen schlechte Kommentare
- Tagebuch Kommentare 🙂 :In Zeiten von SVN und GIT müssen Änderungen am Code nicht mehr im Head vermerkt werden tagebuchartig.
- Kommentare hinter schließenden Klammern: bei langen Funktionen macht das Sinn, wobei dies immer darauf hindeutet schlecht programmiert zu haben!
- Autorennamen von Codeteilen/Änderungen: gehören ins SVN
- Auskommentierter Code: Andere trauen sich nicht den Code zu löschen, weil er vielleicht wichtig seien könnte und so bleibt es bis zum Ende drin. Gehört in Zeiten von SVN auch nicht mehr in den Code.
- HTML-Kommentare: sind schlecht lesbar, ein Werkzeug sollte das übernehmen, z.B. Javadoc oder phpDocumentor.
- kurze Funktionen: sollten nicht kommentiert werden müssen
- Javadoc in nicht öffentlichen APIs: sind unnötig durch die hohe Formalität und durch viele überflüssige, weil vorgeschriebenen, Kommentare
zurück zu Teil 1: Clean Code – Regeln für guten, sauberen Code
Weiterlesen?
