Gibt es eine Methode, um informative Kommentare von auskommentiertem Code zu unterscheiden?

36

Während des Programmierens werden Sie einige Kommentare erhalten, die den Code erklären, und einige Kommentare, die den Code entfernen:

// A concise description 
const a = Boolean(obj);
//b = false;

Gibt es eine gute Methode, um schnell zu analysieren, welche welche ist?

Ich habe mit der Verwendung von /3en und /** */für beschreibende Kommentare herumgespielt.

Ich habe auch ein VSCode-Plugin verwendet, um //TODO:und hervorzuheben//FIXME:

As
quelle
2
Anmerkungen ///und /** ... */Kommentare werden auch von einigen Dokumentationsgeneratoren wie Doxygen oder JSDoc verwendet. Wenn Sie sie oder ähnliche Tools verwenden, können Sie diese Art von Kommentar möglicherweise nicht für beschreibende Kommentare verwenden, die nicht als Teil der Dokumentation gedacht sind.
Justin Time 2 Setzen Sie Monica
1
In Javascript enden die meisten Codezeilen wahrscheinlich mit einem Semikolon. Wenn Ihre Kommentare dies nicht tun, scheint dies ziemlich einfach zu sein, und Sie können auch ein Skript schreiben, um dies zu überprüfen.
Artemis Fowl

Antworten:

187

Hierfür gibt es eine sehr einfache Lösung: Entfernen Sie den auskommentierten Code.

Tatsächlich gibt es nur zwei gute Gründe, um Code zu kommentieren: um etwas zu testen / zu reparieren oder um Code zu speichern, den Sie möglicherweise später verwenden. Wenn Sie etwas testen oder reparieren, entfernen Sie den auskommentierten Code, sobald Sie den Test oder die Fehlerbehebung abgeschlossen haben. Wenn Sie Code speichern, den Sie möglicherweise später verwenden, erstellen Sie ihn als erstklassigen Code und speichern Sie ihn an einem Ort, z.

Robert Harvey
quelle
108
Wenn der Code eingecheckt wurde, entfernen Sie ihn einfach. Wenn Sie es jemals wieder brauchen, haben Sie
Zugriff
38
Wenn Code entfernt wird, bemerkt niemand, dass er jemals existiert hat. Das macht es schwieriger, sich zu erholen. Es ist sinnvoll, kommentierten Code zu hinterlassen, insbesondere wenn es wahrscheinlich ist, dass er in Zukunft verwendet wird.
USR
76
@usr: Wenn Code entfernt wird, merkt niemand, dass er jemals existiert - und meiner Erfahrung nach ist dies in 99% aller realen Fälle das Richtige. Bei 1% ist möglicherweise ein gewisser Wert in den auskommentierten Zeilen enthalten. Wenn jedoch der auskommentierte Code mehrere Wochen oder Monate (oder länger) gespeichert bleibt, ist die Wahrscheinlichkeit groß, dass er aufgrund von Umgestaltungen des aktiven Codes nicht einmal mehr kompiliert wird Codezeilen. Das Argument "Potenzieller Wert für zukünftige Verwendungen" wird oft als falsche Entschuldigung von Menschen verwendet, die ein emotionales Problem haben, Dinge aus der Codebasis zu streichen, für die sie einige Stunden Brainwork investiert haben.
Doc Brown
21
Ich gebe niemals kommentierten Code ohne zusätzliche erklärende Kommentare ein. Es gibt seltene Situationen, in denen Sie den Code kurzfristig zurückhaben möchten, aber jede einzelne davon ist außergewöhnlich und erfordert eine Erklärung für zukünftige Entwickler (oder zukünftige Sie). 90% meiner Kommentare sind "Entfernt, weil es unbenutzt zu sein scheint. Nach Nov 2021 löschen, wenn es keine Probleme gibt"
James Beninger
30
Mein Kollege hat einmal "Es gab hier Code, der X hat, aber ich habe ihn entfernt", als wir vorerst einige Funktionen entfernt haben. Das hat sehr gut funktioniert; Sie wussten, dass es in der Quellhistorie für diese Datei war, aber es hat Sie nicht gestört.
Erik
45

Das Hinzufügen @ RobertHarvey die ausgezeichnete Antwort glaube ich , es nur einen legitimen Grund ist die ich je für das Speichern von kommentierten Code zur Quellcodeverwaltung gestoßen, auch nur vorübergehend: bei nicht offensichtlichen Ersatz - Code, der sollte jetzt nicht oder aus irgendeinem Grund nicht verwendet werden kann , . Selbst dann sollte der Großteil des Kommentars die Erklärung sein, nicht der Ersatzcode. Dies könnte ein Fehler oder eine Eigenschaft der Sprache sein, die noch nicht als stabil angesehen wird. Es könnte ungefähr so ​​aussehen:

# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]

In diesem Fall ist die Arbeit bereits erledigt, Sie können sie jedoch noch nicht nutzen. Wenn Sie sie löschen, muss sie später erneut entdeckt werden. Gleiches gilt für suboptimale Lösungen, die auf den ersten Blick überlegen erscheinen können, oder für bewusste Kompromisse mit ähnlichen Lösungen .

Achtung: Verunreinigen Sie Ihren Code nicht mit alternativen Lösungen. Jede Aufgabe kann auf unendlich viele verschiedene Arten erledigt werden, und es ist nicht wirtschaftlich, diesen Raum für jede Änderung über einen langen Zeitraum zu erkunden. Code Reviews können ein guter Ort sein, um solche fehlenden Kommentare zu entdecken, wenn Ihr Kollege eine Verbesserung vorschlägt, die Sie bereits als suboptimal erkannt haben.

l0b0
quelle
2
Die Kehrseite davon ist, dass Sie manchmal erklären müssen, warum Sie nicht verwenden frobnicate(bar), damit niemand mitkommt und versucht, Ihren "uneleganten" Code zu "reparieren". Sie zeigen ihnen also, dass Sie wissen, dass in einer perfekten Welt die frobnicateFunktion der richtige Weg ist, aber Sie wissen aus schmerzhaften Erfahrungen, dass sie nicht richtig funktioniert. Es kann keine Erwartung bestehen, dass der Dritte es überhaupt für einen Fehler hält, geschweige denn, dass es sich lohnt, ihn zu beheben. Sie müssen den zukünftigen Programmierern (einschließlich Ihnen selbst) noch einen Kommentar dazu hinterlassen, warum Sie nicht den offensichtlichen Ansatz gewählt haben.
Monty Harder
3
Eine verwandte Situation ist, dass es zwei Möglichkeiten gibt, etwas zu tun, von denen eine gültige Daten viel schneller verarbeitet als die andere und eine nützlichere Diagnose bietet, wenn sie aus irgendeinem Grund ungültige Daten empfängt. Wenn das Programm Teil eines Prozesses ist, der nur Daten liefern soll, deren Gültigkeit "garantiert" ist, die jedoch nicht ordnungsgemäß funktionieren, kann eine langsamere Version, die jedoch eine bessere Diagnose bietet, dies bewirken viel einfacher zu bestimmen, was schief geht.
Supercat
20

Hmm, ich habe diese Frage etwas anders gelesen als Robert, der zu Recht behauptet, dass auskommentierter Code entfernt werden sollte.

Wenn Sie jedoch nach einer Konvention suchen, mit der Code zum späteren Entfernen markiert wird, ist einer meiner alten Favoriten:

//b = false; //TODO: remove

Einige IDE-Flag- //TODO:Kommentare oder können gelehrt werden. Wenn nicht, ist es normalerweise eine durchsuchbare Zeichenfolge. Befolgen Sie am besten die Konventionen Ihres Shops, da dies auf verschiedene Arten erfolgen kann. Jede Codebasis sollte dies auf eine Weise tun. Hält es durchsuchbar.

schnell analysieren was ist was?

Ohne diese Markierung erfolgt dies automatisch mit dem Compiler. Wenn das Entfernen des Kommentars zu kompiliertem Code führt, muss es sich um kommentierten Code handeln. Schreiben eines IDE-Plugins, das prüft, ob dies nicht schwierig ist. Aber es wird fehlerhaft kommentierten Code hinterlassen.

Aus diesem Grund ist es besser, auskommentierten Code einfach als Code zu markieren, sobald Sie ihn auskommentieren. Auf diese Weise können Sie zerstörungsfrei arbeiten, während Sie entscheiden, ob Sie es wirklich wollen. Da wir alle unterbrochen werden und etwas vergesslich sind, wundern Sie sich nicht, wenn in diesem Zustand einige Zeilen eingecheckt werden. Wenn sie es tun, ist es schön, dass sie zumindest deutlich gekennzeichnet und durchsuchbar sind. Tastaturmakros haben mir in der Vergangenheit dabei geholfen. Es ist schwer, in der Mitte davon unterbrochen zu werden, wenn Sie es mit einem einzigen Tastendruck tun können.

Sie können dies so weit führen, dass Sie die Marke in Ihren kontinuierlichen Integrationstests verankern. Hoppla, ich versuche erneut, bei hervorragenden TODOs einzuchecken.

kandierte_orange
quelle
Anstatt zu sehen, ob Kommentare kompiliert werden, um sie als Code zu kennzeichnen, können Sie Kommentare durch einen Prozessor in natürlicher Sprache ausführen und diejenigen kennzeichnen, die als Satz oder Nominalphrase in der Sprache Ihres Teams analysiert werden.
TheHansinator
3
@TheHansinator das hört sich gut an aber meine Erfahrung mit meinem Handy macht mich vorsichtig.
candied_orange
Ich stelle mir vor, dass der NLP, der zum Parsen von Codekommentaren verwendet wurde, viel besser wäre als der NLP, der die Autokorrektur unterstützt, einfach weil der Computer den gesamten Satz zum Arbeiten hat und nicht versucht, Rechtschreibfehler zu korrigieren. Ganz zu schweigen davon, dass das falsche Negativ auch hier besser ist - solange ein Mensch in der Lage ist, den Kommentar vor dem Löschen zu überprüfen, kann er den Kommentar einfach umschreiben, anstatt nicht auf nutzloses GobbledyGook aufmerksam gemacht zu werden.
TheHansinator
3
wrt Parsing: double buffer (flip on)-> C-Prototyp oder ultra-knappe Englisch? Ich kann es nicht ohne Kontext sagen, kein korrektes vollständiges Konstrukt in einer der beiden Sprachen. Einige falsch-positive und -negative sind unvermeidlich, wenn Kommentare ihrer Natur nach die Form ihres Inhalts in keiner Richtung einschränken.
Leushenko
8

Ich verwende Präprozessor-Direktiven, um Code zu entfernen, keine Kommentare:

//comment
active_code();
#if FALSE
inactive_code();
#endif

Das macht das Suchen sehr einfach und mein Syntax-Textmarker behandelt es als Kommentar. Ich kann es sogar zu einer einzigen Zeile zusammenfassen:#if FALSE(...)

Sie können diese Idee erweitern, um mehrere Optionen zu haben:

#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif

Und Fehlerüberprüfung zur Kompilierungszeit:

#if FOO >= 5
#error FOO should be less than 5!
#endif

Natürlich wollen Sie nicht über Bord gehen, oder es wird schwierig zu sagen, was tatsächlich kompiliert wird und was nicht. Aber Sie haben die Idee, und es ist sowieso das gleiche Problem wie für kommentierten Code ... solange Sie ihn nur statisch verwenden. Wenn Ihre Bedingungen dynamisch sind, ist es schlimmer.


Um herauszufinden, welche Codebasis welche ist, die dieses Problem überhaupt nicht berücksichtigt hat, gibt es meines Erachtens keine universelle Lösung. Sie müssen selbst Muster finden und wahrscheinlich einen regulären Ausdruck codieren, um sie zu finden.

AaronD
quelle
Wofür in aller Welt wäre das gut? Müssen Sie mehrere Versionen kompilieren?
Tvde1
@TVDE1 Das ist eine Möglichkeit und ein möglicher Albtraum, wenn du es nicht wirklich gut schaffst . Aber die Alternative ist möglicherweise schlimmer. Wenn Sie über mehrere Kopien fast desselben Codes verfügen, eine für jede Variation eines gemeinsamen Themas, müssen Sie diese separat verwalten und synchron halten.
AaronD
Es gibt verschiedene Möglichkeiten, dies zu tun, aber alle haben Variationen des komplexen Konfigurationsproblems oder des Problems mit unabhängigen Kopien: Sind Sie sicher, dass alle unabhängigen Kopien einen Bugfix erhalten haben? Was ist, wenn nicht, und ein weiteres Feature hinzugefügt wird, das dann durch den Bugfix beschädigt wird, der vor dem Feature bekannt war, aber bisher nicht portiert wurde?
AaronD
3
Das funktioniert nur , wenn Sie haben einen Vorverarbeitungsschritt wie C. Die Frage ist javascript. Sie könnten eine Vorverarbeitung durchführen, aber dies wird die Fähigkeiten des Build-Systems erweitern und auch nicht dem Standard entsprechen. Wenn Sie kein Build-System haben oder das Build-System das Parsen und Ausführen von Code überhaupt nicht unterstützt, können Sie diese Lösung nicht implementieren. Schließlich wird die Frage nicht einmal angesprochen - auskommentierter Code entspricht nicht unbedingt dem Code, der bedingt aktiviert ist. Es könnte sich um einen Rest handeln, der nicht aktiviert werden soll.
VLAZ
Die bedingte Aktivierung ist nur eine Erweiterung der Antwort und nicht der Antwort selbst. Andernfalls würde ich es bearbeiten, um die Kommentare einzuschließen, die es noch weiter ausdehnen.
AaronD
4

Ich stimme der Antwort zu, dass alter Code entfernt und nicht auskommentiert werden sollte, obwohl ich in den wenigen Fällen, in denen auskommentierter Code benötigt wird, eine Konvention eingehalten habe.

(Meine Basis ist C #, aber dies kann auf jede C-Syntax-Sprache angewendet werden, zB Java)

// An explanatory comment has a space between the comment marker and the content.

// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
//   doSomethingElse();
//}
IanF1
quelle
2
Das hängt ganz vom Stil ab: Wenn ich Code auskommentiere, füge ich im Allgemeinen //die erste Spalte hinzu, und da praktisch der gesamte Code eingerückt ist, beginnt der Kommentar praktisch immer mit einigen Tabulatoren. Normale Kommentare erhalten von mir kein führendes Leerzeichen, es sei denn, es gibt bereits andere Kommentare mit einem führenden Leerzeichen in der Nähe. Daher würde Ihre Methode bei Kommentaren, die ich erstellt habe, miserabel scheitern, und jede Methode, die zum Erkennen meiner Kommentarmuster entwickelt wurde, würde bei Ihren Kommentaren miserabel scheitern.
6.
@cmaster Ah ich verstehe, ich glaube ich habe die Frage falsch verstanden. Ich habe eine einfache Möglichkeit bereitgestellt, die Kommentare so zu formatieren, dass sie leicht nach Typ analysiert werden können, was nicht gewünscht ist.
IanF1
2

Ich interpretiere die Frage immer noch anders und denke, Sie möchten auskommentierten Code finden.

C-Code muss Semikolons enthalten, während in Kommentaren Semikolons unwahrscheinlich sind. Für einzeiligen auskommentierten Code können Sie also diesen regulären Ausdruck verwenden:

\s*\/\/[\s\S]*;

Bei mehrzeiligem auskommentiertem Code könnte es sein

\/\*[^\;]*;[^\;]*\*\/

Hinweis: Visual Studio ist etwas eigenartig in Bezug auf Zeilenumbrüche in regulären Ausdrücken. Sie zählen nicht als Leerzeichen. Sie müssen ein explizites \ n angeben.

Martin Maat
quelle
2

Wenn Sie einen Editor mit einem im Hintergrund laufenden Compiler (wie Xcode und Clang) verwenden, können Sie einfach versuchen, den Text des Kommentars zu kompilieren. Zum Beispiel gibt "eine kurze Beschreibung" Fehler aus, "b = false;" nicht. Sie könnten dann eine andere Syntaxhervorhebung verwenden.

Eine einfachere Methode wäre ein IDE-Plugin, das einige Heuristiken verwendet, z. B. mehrere Wörter in einer Reihe, außer Schlüsselwörtern, die auf Kommentare verweisen, geschweifte Klammern, die auf Code verweisen usw.

gnasher729
quelle
1

Andere Antworten haben Variationen des Themas "Code nicht auskommentieren" behandelt. Aber manchmal möchten Sie es trotzdem als Referenz haben.

Wenn Sie den Code wirklich brauchen, um in der Nähe zu bleiben, ist es eine bessere Lösung, den Code mit "#if 0 ... #endif" zu umgeben, idealerweise mit einem Kommentar, aus dem hervorgeht, warum. Dies ist die empfohlene Strategie aus verschiedenen Codierungsstandards, einschließlich MISRA.

Graham
quelle
-3

Zumindest für mich einfach - und in C / C ++. Die Kommentare in / * * / sind informativ. Testcode, der vorübergehend entfernt wird, wird mit führendem // auskommentiert.

Und es gibt gute Gründe, Testcode in der Datei zu belassen, aber auskommentiert, zumindest in der Art von Arbeit, die ich mache. Früher oder später wird jemand eine Änderung wünschen, die diesen Code benötigt. Das Aufheben des Kommentars für einen Block erfordert einen Editorbefehl, ebenso wie das erneute Kommentieren, wenn Sie fertig sind.

jamesqf
quelle
Es gibt auch #ifdef __DEBUG ... #endifoder welche benutzerdefinierte Definition Sie verwenden möchten. __DEBUGist aber schön, weil man oft nur die Projektkonfiguration ändern muss, um es zu bekommen. Mit den meisten IDEs können Sie jedoch auch Ihre eigenen Konfigurationen definieren, die Ihnen an dieser Stelle alles bieten.
AaronD
Was meinst du mit "Testcode"? Unit-Tests? Diese sollten überhaupt nicht auskommentiert, sondern in der Testsuite aufbewahrt und so oft wie möglich ausgeführt werden, unabhängig davon, ob jemand dies für notwendig hält. Sicher, es ist leicht zu re-un-Kommentar ein Stück Code, aber es ist noch einfacher , nicht überhaupt nichts tun und haben die Test - Suite bereits vorhanden , es zu tun ...
leftaroundabout
1
Argh, tu das nicht . Das Auskommentieren von Code "um etwas zu testen" funktioniert 99 von 100 Mal einwandfrei ... und im Einzelfall werden Sie vergessen, ihn zu entfernen (wenn er nicht mehr benötigt wird) oder - noch schlimmer - das Auskommentieren zu vergessen ( wenn es gebraucht wird) und die Dinge können hässlich werden.
CharonX
@leftaroundabout: Nein, ich meine Dinge wie printf-Anweisungen, mit denen Werte überprüft werden.
Jamesqf
@jamesqf du solltest niemals so etwas brauchen, dafür ist ein Debugger da. Aber selbst wenn Sie printf/ coutoder Ähnliches verwenden, um neu geschriebenen Code richtig zu machen (was ich selbst zugegeben habe), ist es nicht sehr effektiv, sie dort zu belassen. Wenn jemand Änderungen vornehmen möchte und weiß, zu welchen Variablen er Informationen benötigt, kann er diese schnell und einfach neu schreiben. printfWenn dieser Entwickler jedoch nicht weiß, was benötigt wird, und alle diese printfAnweisungen einfach auskommentiert, dann ist der riesige Textbereich drin Das Terminal wird ihnen wahrscheinlich auch nicht helfen.
Abfahrt um den