Sind veraltete Kommentare ein urbaner Mythos?

38

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?

Karl Bielefeldt
quelle
30
Einverstanden. Aus veraltetem Code ist ein Kommentar geworden, von dem ich viel sehe - und von dem ich weniger sehen möchte.
Pyvi
8
Ich sehe mehr Mangel an Kommentaren als irgendetwas. In Kombination mit schlechten Namenskonventionen ist es ein Spaß, einige der Dinge zu lesen, mit denen ich arbeite.
P. Brian Mackey
2
Ich habe eine Menge veralteter Kommentare gesehen, einige waren einfach nur irreführend. Definitiv kein Mythos, aber meistens gültig für Projekte, die von vielen Menschen und / oder für lange Zeit gepflegt werden, verstärkt durch Komplexität. Ich habe jedoch gelernt, dem Code zu vertrauen, nicht den Kommentaren (ich habe sie fast nie gelesen, wenn sie mehr als zwei Zeilen überschreiten).
MaR
Ich habe während meiner gesamten Karriere hauptsächlich mit einem sehr alten Legacy-Code gearbeitet. Es gab ungefähr ein Dutzend Male, in denen ich schwerwiegende Probleme im Zusammenhang mit veralteten Kommentaren in einem 30 Jahre alten Fortan77-Code hatte, aber es war fast null Prozent des Codes, in dem Kommentare angemessen waren. Also stimme ich zu, das Ausmaß eines Problems muss übertrieben gewesen sein.
SK-logic
Nur mein Glück, ich habe in dem Jahr, seit ich dies gepostet habe, einige gesehen. Ich hatte wohl unbewusst gelernt, ihnen nicht zu vertrauen, sie dann zu korrigieren und weiterzumachen, ohne mir genug Gedanken zu machen, um sie in mein Langzeitgedächtnis zu schreiben.
Karl Bielefeldt

Antworten:

33

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.

Steve Jackson
quelle
Im Grunde genommen sagen Sie also, Sie ignorieren Kommentare einfach vollständig, weil es bereits zu chaotisch ist, was Ihre Situation nur noch verschlimmert. Kaum überraschend.
Steven Jeuris
5
@Steven - Ich persönlich, nein. Ich glaube fest an eine schrittweise Verbesserung. Ich habe Knurren von völlig nicht entzifferbarem Code gesehen, die sich mit genügend schrittweiser Anstrengung in etwas Anständiges verwandelt haben. Ignorieren ist jedoch nach meiner Erfahrung die Norm. Es ist sehr verständlich, dass veraltete Kommentare bei mehreren miteinander verflochtenen 10000-Zeilen-Klassen mit wochenlangen Problemen beim Katalogisieren in der Regel ganz unten in der Prioritätenliste stehen.
Steve Jackson
1
@Steve: In deiner Situation würde ich einfach ein Skript erstellen, das dann alle Kommentare entfernt und anfängt, bei Bedarf von vorne zu kommentieren. :)
Steven Jeuris
1
Die Hauptcodebasis, in der ich früher gearbeitet habe, waren mindestens halbe Kommentare und selten kommentierter Code. Veraltete Kommentare waren eine Tatsache, korrekte Kommentare waren äußerst selten und ich werde nicht einmal anfangen, die Dokumentation zu kommentieren !!! Anblick ... Nach diesem Job habe ich gelernt, dass weniger gut ist. Wenn Sie Code kommentieren müssen, ist wahrscheinlich ein Refaktor erforderlich, um die Dinge deutlicher zu machen ...
Newtopian
4
Ich habe einige schreckliche Beispiele dafür gesehen Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here. Beispiel: Kommentare auf Klassenebene, die sich auf eine andere Klasse beziehen.
Peter Taylor
18

"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.

Steven Jeuris
quelle
Da ich besser geworden bin, brauche ich weniger Kommentare, um zu verstehen, was Code in typischem Plug-n-Chug-Code bewirkt.
Paul Nathan
3
@Paul Nathan, Kommentare sollten niemals beschreiben, was der Code tut - der Code beschreibt das besser. Kommentare sollen erklären, warum der Code das tut, was er tut.
SK-logic
2
@ SK-logic: Obwohl ich das Argument verstehe, glaube ich, dass es zu weit gefasst ist. Die Kommentare einer Funktion (oder eines Code-Absatzes / Blocks) können viel klarer (und schneller) machen, was die Funktion tut, als ihr Name. Dies ist insbesondere für öffentliche Funktionen erforderlich. So einfach der Code zu lesen ist, so schneller ist das Lesen einer Erklärung mit zwei Zeilen für 10-Zeilen-Code. Stellen Sie sich vor, Sie arbeiten mit Ihrer bevorzugten API, die keine "Was" -Dokumentation enthält. Sie wären sich in Bezug auf die Funktionalität viel weniger sicher.
Steven Jeuris
Ja, ich habe keine Dokumentation beigefügt (z. B. Javadoc). Sie ist zu strukturiert, um nur als " Kommentare " bezeichnet zu werden.
SK-logic
17

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.

Bobby Tische
quelle
"Veraltete Kommentare riechen nach Arbeit." Sehr gut gesagt! Ebenso ist selbstdokumentierender Code nur ohne Kommentare nicht die Lösung, sondern ein fauler "Hack".
Steven Jeuris
10

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.

Kim.Net
quelle
Kann ich fragen, in welchen Branchen Sie gearbeitet haben? Ich frage mich, ob dies bei einigen häufiger vorkommt als bei anderen.
Karl Bielefeldt
Ich habe in 3 verschiedenen Ländern in Europa gearbeitet, hauptsächlich als Berater für ein großes und ein kleines Unternehmen. In letzter Zeit in einem SaaS-Entwicklungshaus.
Kim.Net
10

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.

Deckard
quelle
3
(Keine Kritik - nur eine Lösung) IDE-Warnungen können einen großen Beitrag dazu leisten, dies zu verhindern. Wenn drastischere Maßnahmen erforderlich sind, schlagen Sie die Warnung / den Fehler bei der Erstellung eines Javadoc-Builds fehl.
Michael K
1
Dies könnte erklären, warum ich nicht sehr viele gesehen habe. Ich habe noch nie an einem Ort gearbeitet, der Kommentare im JavaDoc-Stil verwendet.
Karl Bielefeldt
4
@Michael, IDE-Warnungen sind in leichten Fällen hilfreich. Unsere alte Codebasis erzeugt über 20.000 Checkstyle-Warnungen. Das ist weit über die Grenze hinaus, wo Sie aufhören zu achten: - (((IDEs können, wenn sie schlecht verwendet werden, erheblich zum Javadoc-Elend beitragen. Der größte Teil des Javadoc in unserer Codebasis wurde offensichtlich automatisch generiert.
Péter Török
4

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.

Dyppl
quelle
3

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.

Bill Leeper
quelle
2

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.

Dave Wise
quelle
2

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.
Morgan Herlocker
quelle
1
Das Problem in diesem Fall ist wahrscheinlich der Missbrauch von TODOs. Ich bin der Meinung, dass TODOs nur verwendet werden sollten, wenn der Code tatsächlich funktioniert, aber Verbesserungen später vorgenommen werden können. Daher sollten TODO: implementkeine Kommentare vorhanden sein und die Tatsache, dass tatsächlich niemand zurückgekehrt ist, spielt keine Rolle. Leider halten sich nicht viele Menschen an diese Regel und ich stimme voll und ganz zu, dass ich einen Kommentar sehen möchte, wie Sie ihn irgendwann in einem Produktionscode gepostet haben. Es würde meinen Tag machen.
Pwny
1
In C # verwende ich die NotImplementedException für diese Zwecke.
Steven Jeuris
2
@pwny, ich verwende TODOs nur für Dinge, die ich vor dem Einchecken schreiben möchte, um sicherzugehen, dass ich mich damit befasse. Alles, was längerfristig ist, gehört meiner Meinung nach in einen Bug-Tracker.
Karl Bielefeldt
@Karl Bielefeldt Das macht auch sehr viel Sinn.
Pwny
2

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.

jwenting
quelle
1

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.

JeffO
quelle
0

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.

Gaurav Sehgal
quelle