Warum ist es falsch, Code zu kommentieren und ihn dann nach und nach zu entfernen, um zu verfolgen, was ich bereits getan habe und was noch zu tun ist?

21

Immer wenn ich feststelle, dass ein großer Teil meines Codes geändert werden muss, entweder weil er falsch ist oder weil er an wichtige architektonische Änderungen angepasst werden muss, die aus anderen Gründen erforderlich sind, ist dies das, was ich normalerweise tue:

  1. Ich kommentiere den gesamten Code aus, von dem ich vermute, dass er möglicherweise geändert werden muss. Ich behandle den auskommentierten Code als eine Art meiner TODO-Liste.
  2. Ich überprüfe nach und nach den auskommentierten Code und entkommentiere Teile dieses Codes oder füge sie an einer anderen Stelle ein und bearbeite sie dann nach Bedarf oder schreibe Teile dieses Codes von Grund auf neu, wobei ich den auskommentierten Code als Referenz betrachte. Wann immer ich denke, dass ich mit einem Teil des auskommentierten Codes fertig bin, entferne ich ihn.
  3. Ich mache so lange weiter, bis ich keinen auskommentierten Code mehr sehe.

Ich sollte beachten, dass ich dies größtenteils bei dem persönlichen Projekt mache, das ich alleine entwickle.

Mir wurde jedoch gesagt, dass ich damit aufhören sollte. Mir wurde gesagt, dass ich stattdessen anfangen sollte, git zu verwenden, indem ich auf alte Commits verweise, um alten Code zu sehen, anstatt auskommentierten Code zu hinterlassen. Mir wurde gesagt:

Das Auskommentieren von Code ist eine schlechte Angewohnheit, die beseitigt werden sollte. Ihnen fehlt die Erfahrung, deshalb verstehen Sie das nicht. Wenn Sie in ein paar Jahren den Code einer anderen Person sehen, die den Code gerne auskommentiert, werden Sie selbst anfangen, diese Person zu beschimpfen. Immer wenn ich auskommentierten Code sehe, entferne ich ihn vollständig, ohne ihn überhaupt anzusehen, da dieser Code normalerweise völlig wertlos ist. Sie werden sicherlich die Nachteile des Auskommentierens von Code in kleinen Ein-Personen-Projekten nicht bemerken. aber wenn Sie einen Job finden und diese Gewohnheit dort behalten, ist es eine Schande.

Darf ich fragen, was sind diese Nachteile von dem, was ich tue, das ich jetzt nicht sehe?

Ich muss sagen, dass ich nicht wirklich darauf aus bin, nur git zu verwenden, um früheren Code zu sehen. Wie gesagt, ich behandle das Auskommentieren von Code als eine Art ToDo-Liste. Während git mir zeigt, wie der Code früher aussah, zeigt es mir nicht klar, welche Teile des Codes noch überprüft werden müssen und welche bereits fertig sind. Ich fürchte, ich könnte einen Teil des Codes übersehen und Fehler einführen.

Der Vollständigkeit halber sollte ich hinzufügen, dass die Person, die ich zitiere, ein erfahrener Entwickler und ein Fan von Onkel Bobs "Clean Code" ist - und Onkel Bob kritisierte es, den Code in seinem Buch scharf zu kommentieren.

Gaazkam
quelle
Übernehmen Sie den kommentierten Code für die Versionskontrolle?
Hören Sie auf, Monica
1
@Goyo Ich habe die Versionskontrolle überhaupt nicht verwendet. Mir wurde gesagt, dass ich definitiv mit der Versionskontrolle beginnen sollte (auch wenn es sich um ein persönliches Ein-Mann-Projekt handelt), und dass unter anderem die Versionskontrolle es mir ermöglichen wird, den Code nicht mehr auszukommentieren (was ich tun sollte).
Gaazkam
4
Wenn der kommentierte Code nach dem Zusammenführen im Hauptzweig nicht sichtbar ist (und Sie können dies tun), wer wird verletzt? Wenn Sie sich verpflichtet fühlen, bevor Sie den auskommentierten Code entfernen, der darauf hindeutet, dass Sie möglicherweise zu große Schritte unternehmen, ist dies eine andere Sache.
Hören Sie auf, Monica
4
Es ist wahr, dass Sie Code leicht rückgängig machen können, indem Sie ihn auskommentieren. Wenn Sie jedoch einige Dinge in einigen Dateien geändert haben und zurückgehen müssen, sind Sie ohne Versionskontrolle ziemlich durchgeknallt. Also sollte "Verwendung der Quellcodeverwaltung starten" weit über Ihrer Priorität liegen als "Code nicht kommentieren" :)
Walfrat
2
Warten Sie, Sie haben geschrieben, Sie hätten eine Codebasis, die groß genug ist, dass Teile davon manchmal "an große architektonische Veränderungen angepasst werden müssen" - und Sie verwenden derzeit KEINE VERSIONSKONTROLLE? WTF - im Ernst? Sie scherzen, nicht wahr? Wenn das wirklich zutrifft, haben Sie größere Probleme als die Frage, ob Ihre Arbeitsweise mit auskommentiertem Code in Ordnung ist oder nicht.
Doc Brown

Antworten:

29

Wenn Sie letztendlich den gesamten auskommentierten Code entfernen, sehe ich kein wirkliches Problem damit. Kommentierten Code in Ihrer Codebasis zu belassen ist eine schlechte Praxis, aber das ist nicht das, was Sie tun, wenn Sie alles durcharbeiten und es beseitigen. Ich vermute, dass die Person, mit der Sie sprechen, den von Ihnen verwendeten Prozess entweder nicht versteht oder dogmatisch ist.

In Wirklichkeit ist kommentierter Code harmlos. Das Problem ist, dass es unordentlich ist und das Lesen erschwert. Es gibt weitaus schlimmere Sünden, aber es ist sehr einfach, sie zu beseitigen. Als die Person, die den Code auskommentiert hat, können Sie am besten feststellen, dass er vollständig entfernt werden kann.

Viele IDEs und Code-Editoren verstehen eine Art TODO-Syntax in Kommentaren. Dies ist eine alternative Methode, um zu markieren, was geändert werden muss. Vielleicht möchten Sie dies berücksichtigen, da es ein wenig mehr Informationen darüber gibt, was Sie gedacht haben, als Sie es markiert haben.

Am Ende des Tages tun Sie die Dinge so, wie es für Sie am besten ist. Selbst wenn dies ein Teamprojekt wäre, belasten Sie niemanden, solange Sie den gesamten kommentierten Code entfernen.

JimmyJames
quelle
Ich kann mich nicht erinnern, wo ich es gehört habe, aber es gibt ein Argument, dass auskommentierter Code im Allgemeinen nicht harmlos ist, da er nie überarbeitet wird. Beachten Sie, dass dies voraussetzt, dass Sie diesen Codeblock irgendwann auskommentieren und erneut verwenden.
Peter M
@ PeterM Der Punkt hier ist, dass es in Ordnung ist, solange Sie es loswerden. Sie sollten keinen kommentierten Code in Ihrer Codebasis hinterlassen. Was ich beim Refactoring oft mache, ist, Variablen auszukommentieren, um zu sehen, wie viele Fehler erzeugt werden, um mir zu helfen, zu verstehen, wie viel Arbeit es sein wird. Je nachdem, was ich vorhabe, kann ich es so belassen, bis ich alle diese Probleme gelöst habe und die Änderung durch Löschen des kommentierten Codes abschließt.
JimmyJames
Ich habe mehrere Codebasen, an denen ich arbeite und die mit TODO- Kommentaren übersät sind . Es ist ehrlich gesagt nicht so schlimm, weil es normalerweise 1-2 Zeilen sind. Was mir an TODO- Kommentaren gefällt, ist, dass meine IDE in der Nähe des Terminals eine Registerkarte „TODO“ hat, auf der sich automatisch diese Kommentarliste mit einer Vorschau des Kommentars und der Datei- / Zeilennummer befindet. Punkt ist, es sinnvoll ist , wenn in einer bestimmten Firma sie nicht keuchen Gebrauch Probleme , obwohl sie Git / Github verwenden. Was können Sie tun, um das Management davon zu überzeugen, Git Issues anstelle von Google Sheets zu verwenden? Ja, versucht und gescheitert. Naja. TODO kommentiert es ist!
Chris Cirefice
6

Darf ich fragen, was sind diese Nachteile von dem, was ich tue, das ich jetzt nicht sehe?

Wohl keine, wenn Sie alleine arbeiten und keine Versionskontrolle verwenden und das Gefühl haben, dass es in Ordnung ist, dies auf diese Weise zu tun.

Tatsächlich spielt es ohne Versionskontrolle keine Rolle, was Sie zu irgendeinem Zeitpunkt tun, da der Code immer den Status hat, in dem die aktuelle Datei wie im Betriebssystem "gespeichert" ist.

Wenn Sie die Versionskontrolle verwenden und eine Vielzahl von Kommentaren als "Aufgabenliste" haben und einige korrigieren und den Kommentar entfernen, dann wiederholen, dann wiederholen, usw., dann werden Code und Kommentare für "In Bearbeitung" gespeichert in Ihrem Revisionsverlauf. Dies ist kein Problem, wenn Sie später kein Rollback auf ein anderes Commit oder gar "Cherry Pick" durchführen müssen (hier nehmen Sie beispielsweise bestimmte Commits und ziehen sie in einen anderen Zweig, um sie zu verwenden). Aber sonst könnte es ein Problem sein.

Vermutlich kann dies mit "Schnappschüssen" der Festplattensoftware verglichen werden, die Windows hatte (die Wiederherstellungssache). Wenn ein Snapshot mit einem Virus erstellt wird, töten Sie den Virus, müssen aber später einen Rollback durchführen, können Sie zu einem Punkt zurückkehren, an dem der Virus wieder vorhanden ist.

Dieser Ansatz ist wahrscheinlich auch ein Problem, wenn Sie die Versionskontrolle verwenden und mit anderen Entwicklern arbeiten, da diese dann Ihre Aufgabenliste sehen müssen, die für sie keine Verwendung hat. In der Tat ist es nur Unordnung, die sie ignorieren und umgehen müssen. In unseren Teams entfernen wir immer alle Kommentare wie alten Code oder "Notizen". Es sei denn, sie sind nützlich - dies ist jedoch sehr selten, da wir Dokumentation für "wie es funktioniert" und Software zum Verfolgen dessen, was getan werden muss (auch bekannt als todo) haben.

Wenn Sie an einem größeren Projekt arbeiten, neigen Sie dazu, zusammenzuarbeiten, sich zu engagieren und häufig zu pushen. Daher ist es möglich, dass der Zweig, an dem sie arbeiten, über Ihre TODO-Liste verfügt, wenn sie Ihren Zweig mit ihrem Zweig zusammenführen. Dann ist Ihre TODO-Liste jedermanns Sache: D

Zusammenfassend lässt sich sagen, dass, wenn Sie nicht alleine arbeiten und insbesondere bei der Verwendung der Versionskontrolle, der Verlauf unübersichtlich und für andere Entwickler unübersichtlich werden kann.

Dies ist in mancher Hinsicht eine persönliche Sache, aber die Verwendung einer Codebasis als "ToDo-Liste" ist nicht wirklich ideal. Eines Tages könnten Sie etwas versehentlich zurücklassen oder vergessen, es zu kommentieren oder aus Versehen zu kommentieren.


Wie bei vielen Herangehensweisen an Architektur, Programmierung und wie Sie persönlich oder Ihr Team arbeiten, kann jedes Szenario etwas anderes erfordern. Berücksichtigen Sie also die genannten Nachteile und die Vorteile der Versionskontrolle und entscheiden Sie, ob sie für Sie funktioniert .

James
quelle
Aus diesem Grund arbeiten Sie an Feature-Zweigen und verwenden gequetschte Zusammenführungen. Code in Arbeit sollte niemals von einem anderen Entwickler gesehen werden, daher sollte es keine Rolle spielen, mit welcher Methode er entwickelt wurde.
Jules
4

Es hört sich so an, als ob Ihr Rezensent ein wenig dogmatisch ist. Ich bin mir nicht sicher, ob ich jemanden dafür beschimpfe, dass er Code auskommentiert ;-) oder sogar hilfreich ist ;-)

Aber im Ernst, ich denke, Ihr Rezensent hat Recht, dass Sie ernsthaft erwägen sollten, git (oder ein anderes Quellcodeverwaltungssystem, aber git ist eine vernünftige Wahl) zu verwenden.

Dies kann dazu führen, dass Sie möglicherweise weniger Code auskommentieren müssen.

Aber eine TODO-Liste im Code zu haben (ob Aufzählungszeichen oder alter Code), ist meiner Meinung nach durchaus vernünftig. Aber vielleicht möchten Sie ein bisschen darüber nachdenken, wie Sie es tun. Zum einen schlage ich vor, an jemanden zu denken, der Ihren Code liest. Das könnte jemand anderes sein, ein Jahr nachdem Sie ein Projekt verlassen und wieder aufgenommen haben. Oder es könnte jemand ganz anderes sein. Nur auf auskommentierten Code zu stoßen, ist ein bisschen verwirrend. Vielleicht so etwas wie:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Persönlich neige ich eher zu so etwas:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

und ich fühle mich frei, "Code-Schnipsel" aus altem Code als hilfreich einzufügen.

Git zu benutzen ist (leider) schwierig. Es wird eine Weile dauern, bis Sie es gelernt haben, und es scheint nicht Teil dessen zu sein, was Sie erreichen wollen. Aber wenn du sinnvoll programmieren willst, musst du lernen, dies als Teil eines Teams zu tun und mit einem Team zu kommunizieren. Genau so wird das heutzutage gemacht. Und wenn Sie erst einmal damit fertig sind, werden Sie feststellen, dass es sich um ein SEHR hilfreiches Tool / eine sehr hilfreiche Krücke handelt, die Ihre Softwareentwicklung erleichtert.

Viel Glück!

Lewis Pringle
quelle
2

Es gibt viele Gründe, Code zu kommentieren: -

  • Es ist noch nicht richtig, und du wirst es entkommentieren, wenn es fertig ist.
  • Sie kommentieren es vorübergehend aus, um das Verhalten beim Debuggen zu ändern.
  • Sie sind sich nicht sicher, ob der Code benötigt wird, möchten ihn jedoch erst löschen, nachdem Sie weitere Tests durchgeführt haben.
  • Der Code wird für einige Versionen der Software benötigt, jedoch nicht für diese.
  • Der Code ist veraltet, aber es hat ewig gedauert, ihn zu schreiben, und Sie sind emotional daran gebunden. Außerdem könnte es eines Tages nützlich sein.

Das Problem tritt auf, wenn Sie den Code ins Bett legen und einige Jahre später erneut darauf zugreifen, um Wartungsarbeiten durchzuführen. Sie finden die Codebasis übersät mit auskommentiertem Code. Es wird nicht mehr klar sein, warum irgendetwas davon da ist, und es ist jetzt nur noch Unordnung.

Wenn Sie ein halbwegs vernünftiges Tool zur Versionskontrolle verwenden, können Sie jeden Code, den Sie nicht mehr benötigen, kühn löschen, in dem Wissen, dass das Versionskontrollsystem ihn noch gespeichert hat. Ein Dateiunterschied zwischen den Versionen zeigt an, was gelöscht wurde. Sobald Sie die Versionskontrolle implementiert haben, müssen Sie nur noch temporäre Inhalte auskommentieren. Wenn Sie in Dateien, an denen Sie gerade nicht arbeiten, jemals auskommentierten Code finden, können Sie ihn einfach löschen.

Simon B
quelle
1
Dies sind genau die Gründe, warum Sie lieber ein SCM verwenden sollten (und die Kraniche darin)
Timothy Truckle
2

Ich werde nicht wiederholen, warum Sie die Quellcodeverwaltung auch für Ein-Personen-Projekte verwenden sollten, da es viele andere Ressourcen gibt, die Sie dazu auffordern. Ein wesentlicher Nachteil Ihres derzeitigen Ansatzes ist jedoch, dass Sie Code, wenn Sie ihn auskommentieren, vor Ihrer IDE verbergen (wenn Sie keine IDE verwenden, sollten Sie ihn wahrscheinlich in Betracht ziehen).

Wenn Sie beispielsweise eine Methode oder Klasse umbenennen oder die Anzahl der Parameter ändern möchten, die eine Methode benötigt, sollte Ihre IDE über eine Refactor-Option verfügen, mit der alle entsprechenden Referenzen gefunden und entsprechend aktualisiert werden können. t Suche in Kommentaren.

Anstatt zu erraten, wo Sie Änderungen vornehmen müssen, nehmen Sie sie einfach vor und lassen Sie sich von Ihrer IDE mitteilen, wo Ihre Änderungen dazu geführt haben, dass die Dinge kaputt gegangen sind. Sie können den Code dann chirurgischer und hoffentlich für einen kürzeren Zeitraum auskommentieren, bevor Sie das Problem beheben.

Chris Cooper
quelle
1

Es ist schlimm und du solltest aufhören .

Der Grund ist, dass versucht wird, eine große Menge an Refactoring in einem Durchgang durchzuführen.

Wenn Sie große Codeabschnitte auskommentieren, ein wenig korrigieren und einchecken, haben Sie nicht funktionsfähigen Code eingecheckt. und eine ganze Menge auskommentierter Sachen, von denen andere annehmen, dass sie alt sind und ignoriert werden können

Wenn Sie nicht oft einchecken, häufen Sie Zusammenführungskonflikte an und zeichnen den schrittweisen Fortschritt nicht auf.

Sie müssen Ihre Arbeitspraxis so ändern, dass alles noch funktioniert, wenn Sie auf halbem Weg anhalten müssen.

Machen Sie kleine Schritte und checken Sie nach jedem ein:

  • eine Schnittstelle extrahieren
  • schreibe einen Test
  • Refactor eine Funktion

Markieren Sie große Codestücke nicht als "Ihre", indem Sie sie auskommentieren, und nehmen Sie sie mit, um sie selbst zu bearbeiten, bis sie vollständig sind oder Sie versagen.

Wenn Sie wissen möchten, was zu tun ist, verwenden Sie ein Task-Board wie Scrum oder Trello

Ewan
quelle