Kommentare im Quelltext sind verboten!
Wie im im letzen Posting bereits angekündigt, werde ich heute einige kuriose Wiederholungen vorstellen. Dazu möchte ich allerdings vorab folgendes anmerken:
Die in diesem Beitrag verwendeten Beispiele, die Quelltexte, die Namen und Personen sind frei erfunden. Die Beispiele sind reine Fiktion. Jegliche Ähnlichkeit mit real existierendem Quellcode, lebenden oder verstorbenen Personen ist rein zufällig.
Ich beginne einfach mit einigen Beispielen.
Beispiel 1:
// Liefert den Namen zurück
public String getName() { ... }
Wo ist nun das Problem? Das Problem liegt darin, dass der Kommentar keinerlei zusätzlichen Informationen enthält. Alles was ich zu dieser Methode wissen muss steht bereits im Methodenname. Selbstverständlich liefert die Methode getName() den Namen zurück, was auch sonst.
Beispiel 2:
// Wenn das Buch im Lager verfügbar ist, dann true
// Wenn das Buch nicht im Lager ist, dann false
// sollte es keinen Buch mit dieser ISBN-Nummer im System geben => Exception
public boolean isBookAvailable(String isbnNumber) { ... }
Wo ist hier das Problem? Hier ist es ein klassischer Fall, der Programmierer hat sich im Vorfeld den Ablauf in Pseudocode oder Prosa aufgeschrieben (eine durchaus übliche Vorgehensweise beim Entwickeln von Software). Danach erst hat er den eigentlichen Algorithmus implementiert. Kommt es nun zu einer Änderung im Algorithmus, so wird dies sehr leicht vergessen in dem Kommentar nachzutragen. Eine mögliche Änderung könnte z.B. das Weglassen der Exception sein. Hier ist nicht die Frage ob man daran denkt den Kommentar zu ändern, sondern wann man es vergisst.
Wie und warum entstehen solche Wiederholungen?
Oft entstehen solche Konstrukte durch einen Standard an den sich der Programmierer mit aller Gewalt halten will/soll. Eventuell gibt es Richtlinien für die Dokumentation des Sourcecodes, in denen steht, dass jede Methode dokumentiert werden muss. Weiterhin haben viele Programmierer gelernt Ihren Quellcode zu dokumentieren.
Guter Quelltext habe viele Kommentare. Leider erzählt ihnen niemand, wieso Quelltext Kommentare braucht. Schlechter Quelltext verlangt besonders viele Kommentare. [Der Pragmatische Programmierer].
Solche Vorschriften und falsch verstandene Ratschläge führen unter anderem dazu die gleichen Informationen am mehreren Stellen zu hinterlegen. Im Beispiel 1 sind Informationen im Kommentar und im Methodenname hinterlegt. Wenn wir auf dieses Beispiel das DRY-Prinzip anwenden, dann kann der Kommentar ersatzlos entfernt werden. Das DRY-Prinzip besagt, unter anderem, das Kommentare für abstrakte Erläuterungen verwendet werden sollen. Werden Kommentare wie in den Beispielen verwendet, dann müssen wir bei jeder Veränderung den Quelltext und den Kommentar anpassen. Die Kommentare werden mit der Zeit unweigerlich veralten und falsche Informationen enthalten.
Falsche Kommentare sind schlimmer als gar keine.
Wo können Kommentare sinnvoll sein?
Es gibt viele Situationen in denen Kommentare sinnvoll sind. Zum Beispiel kann es Sinn machen bei einer Sortiermethode die Art des verwendeten Algorithmus zu dokumentieren. Dann braucht ein anderer Entwickler nur kurz den Kommentar zu lesen und weis wie die Methode arbeitet, er muss also nicht erst die komplette Methode analysieren.
Fazit
Ich will mit diesem Beitrag keinesfalls sagen, dass Softwareentwickler gänzlich auf Kommentare verzichten sollten. Ganz im Gegenteil, ich will, dass sich Softwareentwickler darüber Gedanken machen an welchen Stellen ein Kommentar angebracht ist. Es ist also keinesfalls so wie in der Überschrift angedeutet wird.
Wie gehst Du mit Kommentaren im Quellcode um? Dokumentierst Du alles oder nur die wichtigen Stellen oder schreibst Du vielleicht gar keine Kommentare in den Quelltext?
Dein Feedback ist mir wichtig! Beitrag kommentieren...
Comments
Stimmt, die Beispiele sind wirklich harmlos. Die echten Knaller kann man ja leider nicht erfinden, sondern nur finden.
Wenn Du Beispiele hast, dann immer her damit.
[...] Kommentar von Ulli hat mich gerade auf eine Idee gebracht. Wie ich in meiner Antwort schon geschrieben habe, kann man [...]
[...] hätte. Die Befürworter obiger Konstrukte tun so als hätten selbige erst die IT-Industrie möglich gemacht. Nur war es anders herum. Die IT-Industrie war bereits da bevor diese rein virtuellen [...]
Diese Quellcode-Schnipsel sollen erfunden sein?
Ausserdem sind die Sachen aus dem Posting ja noch harmlos: Ich sag’ nur ‘Julia’! (Die Leute, die es wissen müssen, wissen was ich meine.)
Bei Gelegenheit stöbere ich mal in meinem Archiv und poste hier ein paar richitg geile Sachen.