Sind veraltete Kommentare ein urbaner Mythos?

Ich sehe ständig Leute, die behaupten, dass "Kommentare dazu neigen, veraltet zu sein". Die Sache ist, ich denke, ich habe vielleicht zwei oder drei veraltete Kommentare in meiner gesamten Karriere gesehen. Veraltete Informationen in separaten Dokumenten kommen immer wieder vor, aber meiner Erfahrung nach sind veraltete Kommentare im Code selbst äußerst selten.

Habe ich gerade Glück gehabt, mit wem ich zusammenarbeite? Sind bestimmte Branchen anfälliger für dieses Problem als andere? Haben Sie konkrete Beispiele für kürzlich veraltete Kommentare, die Sie gesehen haben? Oder sind veraltete Kommentare eher ein theoretisches als ein tatsächliches Problem?

Ständig

Ich kann wirklich nicht glauben, dass ich der einzige bin, der in veralteten und irreführenden Kommentaren schwimmt. In der Off-Chance hilft dies beim Verständnis:

Es hängt wahrscheinlich am wichtigsten vom Alter des Codes ab. Der nächste Faktor wäre die Fluktuation des Personals.

Ich mache zu gleichen Teilen F & E- und Wartungsarbeiten. Bei der Forschung und Entwicklung handelt es sich um neuen Code, der in der Regel etwas abseits liegt. Viele meiner Kollegen glauben daran, eine Menge kommentierter Erklärungen abzugeben, wenn sie etwas ausprobieren, für das es noch keine Bibliothek gibt. Da das Kommentar-zu-Code-Verhältnis höher als normal ist, gibt es einfach mehr Möglichkeiten, dass Dinge nicht mehr synchron sind.

Der Wartungscode ... Ich bin ein aktiver Betreuer eines Systems, das älter als 10 Jahre ist, und eines anderen Systems, das älter als 5 Jahre ist. Der 10 Jahre alte Code und die Kommentare sind grausam, wie Sie es erwarten würden. Über 10 Jahre hat man eine Menge Hände in der Codebasis und niemand weiß mehr, wie das Ganze funktioniert. Der 5 Jahre alte Code und die Kommentare sind ziemlich gut, weil der Umsatz im Team ziemlich niedrig war.

Ich arbeite mit fast allen Dienstleistungen, auch unsere Produkte sind sehr kundenindividuell.

Spezifische Beispiele:

• Kommentare, die die Leistungsverbesserung für eine bestimmte Methode beschreiben, z. B. das Vermeiden einer Kopie im Speicher. Eine große Sache, wenn ein Top-End-Computer in einem Pentium 2 mit MB RAM, aber kaum ein Problem jetzt.

• TODOs

• Blöcke aus kopiertem Code, einschließlich Kommentaren. Kommentar mag an seiner ursprünglichen Stelle Sinn ergeben haben, macht hier aber kaum Sinn

• Kommentarblöcke über auskommentiertem Code (Wer weiß, wie viele Jahre das schon ist).

In all diesen Fällen ist der Trend zu beobachten, dass die Kommentare und der Code nicht auf der gleichen Ebene wie die Software gehalten werden. IDEs und grundlegende Entwicklergewohnheiten helfen dabei nicht, mein Auge wurde darauf trainiert, an ihnen vorbeizuschnellen. Ich denke, dass es relativ billig ist, veraltete Kommentare in Projekten auf der grünen Wiese und in aktiven Projekten zu vermeiden. Wenn Sie das Code / Kommentar-Verhältnis hoch halten können, ist es keine große Sache, sie auf dem neuesten Stand zu halten. Es ist etwas schwerer zu rechtfertigen, diese Dinge aufzuspüren, wenn für eine Fehlerbehebung in einem Produktionssystem x Stunden veranschlagt sind.

"Kommentare sind in der Regel veraltet."

Ich habe dies oft genug gesehen, um zu wissen, dass dies ein Problem sein kann.

Die Sache ist, ich denke, ich habe vielleicht zwei oder drei veraltete Kommentare in meiner gesamten Karriere gesehen.

Ich glaube, es sollte durchaus möglich sein, in einer Umgebung zu arbeiten, in der sich jeder ausreichend um die Kommentare kümmert und sie pflegt. Es ist nur ein kleiner zusätzlicher Aufwand, Kommentare in der Nähe des Codes, den Sie gerade bearbeiten, zu überprüfen und gegebenenfalls zu aktualisieren. Falls die Kommentare so weit entfernt sind, dass Sie sie nicht sofort bemerken, waren sie ohnehin schlechte Kommentare und hätten überhaupt nicht hinzugefügt werden sollen (oder zumindest nicht dort).

Darüber hinaus folgt in der Regel zusammen mit der Aussage, dass Kommentare dazu neigen, veraltet zu sein, die Aussage, dass dies die Lesbarkeit verringert und die Menschen verwirrt. Das habe ich noch nicht erlebt. Jedes Mal, wenn ich auf einen veralteten Kommentar stoße, sehe ich deutlich, was sich geändert hat, und aktualisiere den Kommentar nur entsprechend, um den neueren Code darzustellen, wenn auch mit einigem zusätzlichen Aufwand.

Eine aktuelle Studie von Roehm et al. 2012 stellt Folgendes fest:

21 Teilnehmer [von 28] gaben an, ihre Hauptinformationen aus dem Quellcode und Inline-Kommentaren zu beziehen, während nur vier angaben, dass die Dokumentation ihre Hauptinformationsquelle ist.

Dies steht im Einklang mit Ihrem Verdacht, dass Kommentare im Code selbst im Allgemeinen immer noch als sehr nützlich angesehen werden. Dies weist darauf hin, dass eine klare Linie zwischen veralteter Dokumentation und veralteten Kommentaren gezogen werden sollte .

_{T. Roehm, R. Tiarks, R. Koschke & W. Maalej (2012, Juni). Wie verstehen professionelle Entwickler Software? In Proceedings der 2012 International Conference on Software Engineering (S. 255-265). IEEE Press.}

Veraltete Kommentare riechen nach Arbeit. Es ist wie mit veralteten oder vernachlässigten Komponententests - es zeigt, dass die guten Prozesse, die früher im Geschäft aktiv waren, in Cowboy-Codierung ausarten. Die richtige "Ingenieurskultur", sich die Zeit zu nehmen, um die Dinge richtig zu machen, ist zusammengebrochen. Das Projekt / Unternehmen wird wahrscheinlich technische Schulden haben.

Kurz gesagt, ja, du hast Glück gehabt. Wenn Sie in Ihrer Karriere eine Reihe von recht gut geführten Läden hatten, ist es durchaus möglich, dass Sie nicht so viel sehen. In typischen, weniger gut geführten Läden verläuft dies jedoch parallel zum Rest des Chaos.

Kommentare sind wie Tests, sie sind sehr gut, wenn sie auf dem neuesten Stand sind, können es aber noch schwieriger machen, den Code zu verstehen, wenn sie nicht vorhanden sind.

Wenn Sie noch nie veraltete Kommentare gesehen haben, hatten Sie großes Glück.

Die meisten Codebasen, mit denen ich gearbeitet habe, waren voller veralteter Kommentare, und ich ignoriere Kommentare in der Regel vollständig, da sie in der Regel eher Verwirrung stiften als helfen.

In JavaDoc werden häufig veraltete Kommentare angezeigt:

• Auflisten von nicht mehr vorhandenen Argumenten
• Nicht alle Argumente erklären (die fehlenden wurden wahrscheinlich später hinzugefügt)
• Ähnliche Dinge für Ausnahmen usw.

Darüber hinaus wird in Kommentaren manchmal Folgendes angegeben: "Tun Sie dies hier für die Leistung", wenn die meisten Leistungsüberlegungen dazu neigen, noch schneller veraltet zu sein als der Code selbst.

Ich beschäftige mich von Zeit zu Zeit mit veralteten Kommentaren. Es ist sicherlich kein urbaner Mythos. Die Leute erwähnen es in Listen der schlimmsten Praktiken nicht, weil es Sie sehr oft trifft, sondern weil es Sie in der Regel viel Zeit und Mühe kostet.

In unserer Codebasis werden die meisten veralteten Kommentare durch die Verwendung des (Anti) Musters zur Beschreibung des Methodenverhaltens in der Nähe des Aufrufs und nicht in der Nähe der Methodendeklaration verursacht. Es passiert, wenn jemand einen langen Teil des Codes in eine Methode extrahiert, die im Moment nur einmal aufgerufen wird, und dann den Methodenaufruf kommentiert. Am Ende haben Sie also Folgendes:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

Und die Methode wird irgendwo unten ohne Kommentare deklariert. Im Laufe der Jahre wird mit diesen Methoden herumgespielt, um Änderungen an Spezifikationen vorzunehmen und Fehler zu beheben. Schließlich wird eine Methode gefunden, die die Liste nicht sortiert und eine Ausnahme auslöst, wenn das leere Feature gefunden wird. Daher ist der obige Kommentar ein veralteter Kommentar, der Sie im Debugger einige Zeit kosten wird. Diese kommen in einigen Codebasen vor.

Fragen Sie sich das. Haben Sie jemals eine Codezeile geändert und die zugehörigen Kommentare nicht geändert oder neue hinzugefügt?

Ich habe mit viel altem Code gearbeitet und die Kommentare sind manchmal nicht einmal relevant.

Zum größten Teil entspricht meine Erfahrung Ihrer, aber ich bin auf einen Fall gestoßen, in dem dies in der gesamten Codebasis zutraf. Es war eine App, die vor Jahren von einem Beratungsunternehmen geschrieben worden war, das nicht mehr "zu guten Konditionen" mit dem Kunden war.

Das Unternehmen hat eine außergewöhnliche Arbeit geleistet, den Code zu kommentieren, aber die Programmierer, die ihn seit der ursprünglichen Übergabe beibehalten haben, waren Teil der Denkweise "nur das ändern, was unbedingt geändert werden muss", was an sich nicht schlecht ist. Leider behielten sie diese Haltung auch gegenüber Kommentaren bei, was im Laufe der Zeit zu einer ziemlich großen Diskrepanz zwischen den Kommentaren und dem Code führte.

Ich sehe nicht zu viele deskriptive Kommentare, die nicht mehr aktuell sind, aber ich sehe viele TODO-Kommentare, die es seit Jahren gibt. Ich wünschte, sie wären wie Zeitkapseln und sagten so etwas:

//TODO: In 15 years AND NO SOONER... actually implement this method.

Bei den letzten drei Projekten, an denen ich gearbeitet habe, habe ich mehrere Tage damit verbracht, veraltete, irreführende und einfach nur nutzlose Kommentare aus der Codebasis zu entfernen. Wo möglich und notwendig, ersetze ich sie durch passendere Kommentare, aber meistens geht es nur darum, den Kommentar zu löschen und weiterzumachen.

Ich habe bei so ziemlich jeder Codebasis, die ich jemals von anderen übernommen habe, dasselbe getan, normalerweise nachdem sie eine Weile nicht mehr gewartet wurde und die ursprünglichen Besitzer längst verschwunden sind und / oder nicht bereit oder nicht in der Lage sind, eine ordnungsgemäße Übergabe durchzuführen.

Es könnte der Rückgang bei der Verwendung von Kommentaren sein. Wieviel Code von irgendjemandem ist qualifiziert? Zum einen muss jemand tatsächlich Kommentare hinzufügen, damit sie veraltet sind. Zweitens muss der kommentierte Code geändert werden. Ich bin nicht sicher, ob ein hoher Prozentsatz des Codes geeignet ist.

Sie müssen sich nur auf einen schlechten Kommentar verlassen, um einen großen Teil einer Anwendung zu ruinieren und viel Zeit zu verschwenden.

In einer Organisation, in der viel Code ausgegeben wird, ist es schwierig, die Kommentare synchron zu halten. Der beste Weg, um zu verstehen, was passiert, ist die Verwendung von Software, die das Kontrollflussdiagramm des Moduls zeichnet, an dem Sie arbeiten. Nur so können Sie immer ein Gefühl dafür bekommen, was die Software tut.