"Kommentare sind ein Code-Geruch" [geschlossen]

100

Ein Kollege von mir glaubt, dass die Verwendung von In-Code-Kommentaren (dh keine Javadoc-Methode oder Klassenkommentare) ein Codegeruch ist . Was denkst du?

Fishtoaster
quelle
44
Ich werde jede Antwort, die "nein" sagt, positiv bewerten.
Nicole
2
@Renesis Das ist der Geruch von Göttlichkeit.
ixtmixilix
107
Ihr Mitarbeiter hat eine umfassende Verallgemeinerung vorgenommen, was automatisch bedeutet, dass er sich irrt. :)
Alex Feinman
5
@ Mongus, ich bin anderer Meinung. Die Kommentare in Ihrem Beispiel sind nicht schlecht, weil es sich um Kommentare handelt, sondern weil sie ZU nahe am Code sind, der sich dann ändert. Sie sollten WARUM und nicht WAS sagen .
5
@Alex, ist das nicht eine pauschale Verallgemeinerung, die daher falsch ist (was dazu führt, dass er sowieso nicht falsch liegt)?

Antworten:

167

Nur wenn der Kommentar beschreibt, was der Code tut.

Wenn ich wissen wollte, was in einer Methode oder einem Block passiert, würde ich den Code lesen. Ich würde sowieso hoffen, dass Entwickler, die an einem bestimmten Projekt arbeiten, zumindest mit der Entwicklungssprache vertraut genug sind, um zu lesen, was geschrieben steht, und zu verstehen, was es tut.

In einigen Fällen extremer Optimierung verwenden Sie möglicherweise Techniken, die es für jemanden schwierig machen, die Funktionsweise Ihres Codes zu verfolgen. In diesen Fällen können und sollten Kommentare verwendet werden, um nicht nur zu erklären, warum Sie solche Optimierungen haben, sondern auch, was der Code tut. Eine gute Faustregel wäre, jemanden (oder mehrere andere Personen) mit der Implementierungssprache und dem Projekt vertraut zu machen, der sich Ihren Code ansieht. Wenn er das Warum und das Wie nicht versteht, sollten Sie sowohl das Warum als auch das Wie kommentieren das wie.

Was jedoch im Code nicht klar ist, ist, warum Sie etwas getan haben. Wenn Sie einen Ansatz wählen, der für andere möglicherweise nicht offensichtlich ist, sollten Sie einen Kommentar verfassen, der erklärt, warum Sie die von Ihnen getroffenen Entscheidungen getroffen haben. Ich würde vermuten, dass Sie nicht einmal bemerken, dass ein Kommentar benötigt wird, bis nach so etwas wie einer Codeüberprüfung die Leute wissen wollen, warum Sie X anstelle von Y verwendet haben - Sie können Ihre Antwort für alle anderen, die sie sich ansehen, im Code festhalten in der Zukunft.

Das Wichtigste ist jedoch, Ihre Kommentare zu ändern, wenn Sie Ihren Code ändern. Wenn Sie einen Algorithmus ändern, müssen Sie die Kommentare mit dem Grund aktualisieren, warum Sie sich für den Algorithmus X statt Y entschieden haben. Veraltete Kommentare sind ein noch größerer Codegeruch.

Thomas Owens
quelle
8
Ich stimme dieser Antwort in Bezug auf Kommentare zu, aber ich habe sie auch als Entschuldigung für den Mangel an Dokumentation gesehen, was falsch ist. Code zu lesen ist manchmal eine Qual. Sie sollten sich den Code für eine Methode nicht ansehen müssen , um herauszufinden, was diese Methode bewirkt. Sie sollten in der Lage sein, dies anhand des Namens herauszufinden und weitere Details aus den Dokumenten zu erhalten. Beim Lesen von Code müssen Sie häufig von Klasse zu Klasse und von Datei zu Datei wechseln. Dies ist insbesondere bei dynamischen Sprachen ein Problem, bei denen das Schreiben einer IDE, die all dies verarbeiten kann, nicht trivial ist.
Davidtbernal
1
Wie auch immer, manchmal muss man auch das WIE kommentieren, wenn es kompliziert ist (besonders wenn es optimiert ist oder irgendeine andere Art von nicht trivialen Operationen). Wenn ich mehr als 5 Minuten mit dem Lesen eines Codeblocks verbringen muss, um zu verstehen, was er tut, kann das ziemlich frustrierend sein ...
Khelben
3
"Nur wenn der Kommentar beschreibt, was der Code tut." Oder wenn der Kommentar beschreibt, was der Code getan hat; Der Code hat sich geändert, der Kommentar jedoch nicht.
Bruce Alderman
1
Wie prüfst du, ob dein Kommentar korrekt ist? Warum schreibst du nicht deinen Kommentar als Test? Jeder zukünftige Betreuer kann den Test als überprüfbare Dokumentation für den Code verwenden. Wenn der Kommentar etwas mit der Ausführung des Codes zu tun hat, dann muss das etwas durchsetzbares sein. Wenn der Kommentar nichts mit der Ausführung des Codes zu tun hat, was macht er dann im Code, wo nur Programmierer hinschauen?
Flamingpenguin
2
@ back2dos, wenn Sie sich beim Lesen des Codes anderer Leute häufig übergeben, bin ich froh, dass wir keine Büros teilen ...
110

Das ist im Moment besonders ärgerlich zu hören. Ich habe dieses Wochenende einige Zeit damit verbracht, mir sehr gut benannten, sehr sauberen, unkommentierten Code anzuschauen, der einen Forschungsalgorithmus implementiert (einen, der eigentlich nicht veröffentlicht ist). Ich bin auf hohem Niveau damit vertraut, der Typ, der neben mir saß, war der Erfinder, und der Code wurde vor ein paar Jahren von jemand anderem geschrieben. Wir konnten es kaum verfolgen.

Ihr Mitarbeiter ist offensichtlich nicht erfahren genug.

Paul Nathan
quelle
16
Ich bin neugierig auf "gut benannten, sehr sauberen, unkommentierten Code", dem man nur schwer folgen kann. Jeder Code, den ich als solchen klassifizieren würde, war sehr einfach zu befolgen. Ich würde sicherlich nicht so weit gehen wie "Ihr Mitarbeiter ist offensichtlich nicht erfahren genug".
Liggy
8
@Liggy: Würde ich. Es ist ein Forschungsalgorithmus, keine Branchenanwendung.
Paul Nathan
9
Ich hatte einmal ein Stück Code, in dem Sie Felder in einem Datenbankspaltenobjekt (von Drittanbietern) in der "falschen" Reihenfolge (definiert durch die "Logik" des Prozesses und unsere Codierungsstandards) ausfüllen mussten - tun Sie dies in der Reihenfolge, die wir angegeben haben würde normalerweise verwenden und es würde abstürzen. Kein einziges Mal, wenn Sie den Code gelesen haben, konnte Ihnen dies sagen, so dass es unbedingt einen Kommentar geben musste - und es war kein Geruch, zumindest nicht in Code, über den wir die Kontrolle hatten (das ist die Quintessenz). Ein völliger Mangel an Kommentaren ist ebenso ein Geruch wie schlechte Kommentare.
Murph
29
Mathe, Mathe, Mathe. Nicht jeder Code implementiert trivialen IoC-Kleber und "Preis * Menge". Komplexe Mathematik kann nicht auf magische Weise selbsterklärend gemacht werden.
bmargulies
4
@Liggy, Code, der komplexe Datenstrukturen implementiert, kann ohne umfangreiche Dokumentation völlig unverständlich sein.
75

Kommentare sollten erklären warum, nicht wie.

HowTypenkommentare werden in der Regel besser mit Refactoring behandelt. Persönlich vermeide ich normalerweise Kommentare zugunsten von Refactoring.

Vor:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

nach:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)
Sam Saffron
quelle
26
Ich stimme dem zu, warum nicht, wie Teil, und Ihr Refactoring funktioniert in diesem Beispiel, aber bei komplexerem Code ist es nicht sinnvoll, eine Menge von Variablen / Funktionen umzubenennen / umzugestalten, und Kommentare sind dort weiterhin erforderlich.
GSto
3
Gutes Beispiel, aber warum arbeitet das System mit Cent im Gegensatz zu Dollar? Diese Frage wird in Finanzsystemen relevant, in denen möglicherweise gebrochene Währungen ins Spiel kommen.
rjzii
3
@Start Der Name der Funktion sollte sagen, was sie tut.
Alb
3
@GSto, ich könnte nicht mehr widersprechen. Wenn der Code komplex ist, sollte er in kleinere Methoden / Funktionen mit entsprechenden Namen unterteilt werden, die die Aktion beschreiben.
CaffGeek
1
Sie setzen voraus, dass Sie die vollständige Kontrolle über die Codebasis haben.
LennyProgrammers
32

Ich erkläre Ihren Mitarbeiter zum Ketzer! Wo sind meine ketzerisch brennenden Stiefel?

Zwanghaftes Kommentieren ist schlecht und bereitet Wartungsprobleme. Kommentare sind kein Ersatz für gut benannte Methoden, Klassen, Variablen usw. Manchmal kann es für den armen Idioten, der den Code warten muss, von unschätzbarem Wert sein, zu sagen , warum etwas so ist in sechs Monaten - besonders, wenn dieser arme Idiot es schafft, Sie zu sein.

Einige aktuelle Kommentare aus dem Code, an dem ich arbeite:


    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

BlairHippo
quelle
7
+1 für nette Kommentare. Keine Menge Code kann sagen "Wenn dies passiert, hat jemand mit den Datenbankdefinitionen rumgespielt".
DistantEcho
9
@ Niphra, na ja, wir könnten einen SomebodyScrewedAroundWithDatabaseException...
@ Thorbjørn +1, Wenn der Code weiß, was falsch ist, dann melde ihn bitte. Die Techniker des Kundensupports können möglicherweise ihre Datenbank neu laden und einen Serviceanruf vermeiden.
Tim Williscroft
@Tim, wie Kunden vielleicht sehen, ist eine neutralere Benennung angebracht.
3
Denken Sie daran: Verwenden Sie niemals alberne Namen. Der Kunde wird sie immer sehen.
Tim Williscroft
29

Im Idealfall sollte der Code so gut codiert sein, dass er automatisch erklärt werden kann. In der realen Welt wissen wir, dass auch sehr hochwertiger Code manchmal kommentiert werden muss.

Was Sie unbedingt vermeiden sollten, ist "Kommentar-Code-Redundanz" (Kommentare, die dem Code nichts hinzufügen):

i++; // Increment i by 1

Wenn es dann ein gutes (und gepflegtes / ausgerichtetes) Code-Design und eine gute Dokumentation gibt, ist das Kommentieren noch weniger nützlich.

Unter bestimmten Umständen können Kommentare eine gute Hilfe für die Lesbarkeit von Code sein:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Vergiss nicht, dass du auch Kommentare pflegen und synchron halten musst ... veraltete oder falsche Kommentare können ein schrecklicher Schmerz sein! Und in der Regel kann zu viel Kommentieren ein Symptom für eine schlechte Programmierung sein.

Lorenzo
quelle
2
Eine gute Namenskonvention und gut strukturierter Code tragen dazu bei, dass Sie weniger Kommentare benötigen. Vergessen Sie nicht, dass jede von Ihnen hinzugefügte Kommentarzeile eine neue zu pflegende Zeile ist !!
Gabriel Mongeon
81
Ich hasse es, wenn Leute dieses zweite Beispiel in Ihrer Frage verwenden. } //end whilebedeutet nur, dass der Anfang der while-Schleife so weit entfernt ist, dass Sie ihn nicht einmal sehen können, und es gibt keine Hinweise darauf, dass sich der betrachtete Code in einer Schleife befindet. Schweres Refactoring sollte gegenüber Kommentaren zur Struktur des Codes ernsthaft bevorzugt werden.
Carson Myers
4
@Carson: Obwohl es allgemein bekannt ist, Blöcke kurz zu halten, heißt das nicht, dass wir sie immer anwenden können.
Wizard79
4
@Carson: Eines der Projekte, an denen ich arbeite, weist eine unzureichende Codeüberprüfung auf, die zu einer Sammlung von JSPs mit der zyklomatischen Komplexität "OMFG JUST KILL YOURSELF" führt. Das Umgestalten der blutigen Dinge bedeutet Tage der Arbeit, die woanders verbracht werden müssen. Diese } // end whileKommentare können ein Lebensretter sein.
BlairHippo
11
@BlairHippo: "[A] Codegeruch ist ein Symptom im Quellcode eines Programms, das möglicherweise auf ein tieferes Problem hinweist." Natürlich ist der Kommentar ein Lebensretter, aber die OMGWTF-Schleife ist das oben erwähnte "tiefere Problem" und die Notwendigkeit des Lebensretters ist ein klarer Indikator;)
back2dos
26

Das kategorische Definieren einer Methode oder eines Prozesses als "Code-Geruch" ist ein "Zelotry-Geruch". Der Begriff wird zum neuen "schädlichen" Begriff.

Bitte denken Sie daran, dass all diese Dinge Richtlinien sein sollen.

Viele der anderen Antworten geben gute Ratschläge, wann Kommentare angebracht sind.

Persönlich verwende ich nur sehr wenige Kommentare. Erläutern Sie den Zweck nicht offensichtlicher Vorgänge und überlassen Sie die gelegentliche Bedrohung durch den Tod jedem, der in Betracht zieht, Dinge, die wochenlanges Abstimmen erfordern, selbst zu ändern.

Alles umgestalten, bis ein Kindergärtner versteht, dass es wahrscheinlich keine effiziente Nutzung Ihrer Zeit ist und wahrscheinlich nicht so gut abschneidet wie eine präzisere Version.

Kommentare wirken sich nicht auf die Laufzeit aus. Das einzige negative Problem, das berücksichtigt werden muss, ist die Wartung.

Rechnung
quelle
8
Ich dachte, "Anti-Muster" sei das neue "schädlich". Ein Code-Geruch ist nur etwas, das für eine mögliche Bereinigung einer genaueren Überprüfung bedarf.
Jeffrey Hantin
1
Ich bin nicht anderer Meinung, dass Anti-Pattern auch qualifiziert ist. Sie werden beide auf diese Weise mit Anti-Muster verwendet, anstatt zu riechen, wenn das Design so komplex ist, dass es offensichtlich eine bewusste Wahl ist. In beiden Fällen bin ich nicht einverstanden mit dem Konzept, dass es in diesen Dingen eine absolute Quelle der Richtigkeit gibt.
Bill
4
+1 für "Alles umgestalten, bis ein Kindergärtner versteht, dass es wahrscheinlich keine effiziente Nutzung Ihrer Zeit ist und wahrscheinlich nicht so gut funktioniert wie eine präzisere Version."
Earlz
23

In einigen Fällen kann keine Menge an guter Benennung, Umgestaltung usw. einen Kommentar ersetzen. Schauen Sie sich dieses Beispiel aus der Praxis an (Sprache ist Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Sieht komisch aus, oder? Wahrscheinlich ein Copy-Paste-Fehler? Schreit nach einem Bugfix?

Nun das gleiche mit Kommentaren:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
user281377
quelle
function prime_extjs_uploadform () {response.contentType = 'text / html'; render '{"success": true}'; } prime_extjs_uploadform ();
DrPizza
23

Das Hauptproblem hierbei ist die Bedeutung des Begriffs "Codegeruch".

Viele Leute (einschließlich Sie, denke ich) verstehen einen Code-Geruch als etwas, das einem Fehler nahe kommt oder zumindest behoben werden muss. Vielleicht sehen Sie es als Synonym für "Anti-Pattern".

Dies ist nicht die Bedeutung des Begriffs!

Die Code-Geruchs-Metapher stammt aus dem Wards-Wiki und sie betonen:

Beachten Sie, dass ein CodeSmell ein Hinweis darauf ist, dass möglicherweise etwas nicht stimmt, und keine Gewissheit. Ein perfektes Idiom kann als CodeSmell angesehen werden, weil es oft missbraucht wird oder weil es eine einfachere Alternative gibt, die in den meisten Fällen funktioniert. Das Nennen von CodeSmell ist kein Angriff. Es ist nur ein Zeichen dafür, dass ein genauerer Blick geboten ist.

Was bedeutet es also, dass Kommentare ein Code-Geruch sind: Wenn Sie einen Kommentar sehen, sollten Sie innehalten und überlegen: "Hmmm, ich spüre einen Hinweis, dass etwas verbessert werden könnte". Vielleicht können Sie eine Variable umbenennen, die "Extraktionsmethode" ausführen - oder vielleicht ist der Kommentar tatsächlich die beste Lösung.

Das ist es, was es für Kommentare bedeutet, Code-Gerüche zu sein.

EDIT: Ich bin gerade auf diese beiden Artikel gestoßen, was es besser erklärt als ich:

Rasmus Faber
quelle
2
Ich bin fassungslos, dass es 2 Monate gedauert hat, bis diese Antwort kam. Es zeigt, wie weit verbreitet das Missverständnis des Begriffs ist.
Paul Butcher
Die allgemeine Fallbehauptung ist immer noch falsch. Sie sagen nicht: "Ich sehe kommentierten Code. Das ist ein schlechtes Zeichen."
Stuart P. Bentley
1
@Stuart: Sie sehen zwei Codestücke, beide mit einer angemessenen Anzahl von Kommentaren. (In dieser Ausgabe geht es nicht um die angemessene Anzahl von Kommentaren, sondern darum, wie Sie den Code anhand der Anzahl von Kommentaren beurteilen.) Einer hat keine Kommentare, der andere hat Tonnen. Was schaust du dir genauer an? - Kommentare sind ein Zeichen dafür, dass Code kompliziert und subtil ist und daher eher Probleme aufweist.
David Schwartz
Das ist die richtige Antwort.
Vidstige
21

Ich denke, die Regel ist ganz einfach: Stellen Sie sich vor, ein völlig Fremder sieht Ihren Code. Sie werden wahrscheinlich in 5 Jahren ein Fremder in Bezug auf Ihren eigenen Code sein. Versuchen Sie, den mentalen Aufwand zu minimieren, um Ihren Code für diesen Fremden zu verstehen.

LennyProgrammierer
quelle
8
+1 Für jeden Entwickler , die diese auf einem einzigen Projekt arbeiten lange genug , um zu erfahren , wurde nicht, glauben Sie mir es wird passieren. Immer wenn ich das auf die harte Tour lerne und meinen eigenen Code neu lernen muss, lasse ich mich nicht zweimal den gleichen Fehler machen und ihn kommentieren, bevor ich zu etwas anderem übergehe.
Nicole
Nein, Sie sollten sich einen Psychopathen vorstellen, der weiß, wo Sie leben: Werden sie gerne Ihren Code pflegen?
Richard
4
Ich werde regelmäßig ein Psychopath, wenn ich unlesbaren Code sehe.
LennyProgrammers
3
5 Jahre? Mehr wie 5 Minuten. ;)
Alex Feinman
11

Eine gute Idee, um die richtigen Kommentare zu haben, besteht darin, zuerst Kommentare zu schreiben.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Auf diese Weise können Sie ganz einfach Methoden extrahieren, um die Kommentare loszuwerden.
Lassen Sie einfach den Code diese Dinge erklären! Sehen Sie, wie dies auf sehr schöne Weise umgeschrieben (ausgeschnitten / eingefügt) wird:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Für Dinge, die nicht getrennt werden können, extrahieren Sie einfach keine Methoden und geben Sie den Code unter den Kommentaren ein.

Dies ist meiner Meinung nach eine nützliche Methode, um das Kommentieren auf ein Minimum zu beschränken. Es ist wirklich sinnlos, jede Zeile zu kommentieren.

Wenn Parameter zu häufig verwendet werden, sollten sie private Mitglieder in Ihrer Klasse sein.

Tom Wijsman
quelle
1
Das ist was ich mache. Wenn Sie der Meinung sind, dass Sie Kommentare benötigen, kann ich Ihnen wärmstens empfehlen, dies als Ersatz zu versuchen.
bzlm
10

Ich denke, die Antwort ist die übliche "Es kommt darauf an". Code zu kommentieren, nur um Code zu kommentieren, ist ein Geruch. Das Kommentieren von Code, weil Sie einen um eine Größenordnung schnelleren undurchsichtigen Algorithmus verwenden, erspart dem Wartungsprogrammierer (normalerweise ich 6 Monate nach dem Schreiben) einen halben Tag, um den Code durchzublättern, um festzustellen, was er tut.

Brandon
quelle
10
// Dear me in the future. Please, resolve this problem.

oder

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.
Zzz
quelle
Ah, herzliche Bitten an das zukünftige Ich.
Anthony Pegram
8

Codekommentare sind definitiv kein "Codegeruch". Diese Annahme beruht in der Regel auf der Tatsache, dass Kommentare veraltet (veraltet) und schwer zu pflegen sein können. Gute Kommentare, die erklären, warum der Code auf eine bestimmte Art und Weise etwas tut, können (und sind normalerweise) wichtig für die Wartung.

Gute Kommentare machen es einfacher zu verstehen, was der Code tut und, was noch wichtiger ist, warum er es auf eine bestimmte Weise tut. Kommentare sollen von Programmierern gelesen werden und sollten klar und präzise sein. Ein Kommentar, der schwer zu verstehen oder falsch ist, ist nicht viel besser, als überhaupt keinen Kommentar zu haben.

Wenn Sie Ihrem Code klare und präzise Kommentare hinzufügen, müssen Sie sich nicht auf den Speicher verlassen, um das „Was“ und „Warum“ eines Codeabschnitts zu verstehen. Dies ist am wichtigsten, wenn Sie sich den Code später ansehen, oder wenn sich jemand anders Ihren Code ansehen muss. Da Kommentare Teil des Textinhalts Ihres Codes werden, sollten sie nicht nur klar geschrieben, sondern auch guten Schreibprinzipien folgen.

Um einen guten Kommentar zu verfassen, sollten Sie Ihr Bestes tun, um den Zweck des Codes (das Warum, nicht das Wie) zu dokumentieren und die Argumentation und Logik hinter dem Code so klar wie möglich anzugeben. Im Idealfall sollten Kommentare gleichzeitig mit dem Schreiben des Codes geschrieben werden. Wenn Sie warten, werden Sie wahrscheinlich nicht zurückkehren und sie hinzufügen.

Sams Teach Yourself Visual C # 2010 in 24 Stunden , S. 348-349.

Scott Dorman
quelle
1
Kommentare können veraltet sein, aber das gilt für alles, was nicht von einem Compiler oder einem Komponententest überprüft wurde, z. B. die Bedeutung von Klassen-, Funktions- und Variablennamen.
LennyProgrammers
@ Lenny222: Ja, Kommentare können abgestanden sein ... was normalerweise auf faule Programmierer hinweist. Wenn der Kommentar beschreibt, warum eine Entscheidung getroffen wurde, warum der Code einen bestimmten Algorithmus zur Berechnung verwendet oder wie der Code funktioniert, dann gibt es keinen Grund, dass der Kommentar veraltet ist, außer dass jemand die Implementierung ändert und den Kommentar nicht entsprechend aktualisiert - was gleichbedeutend mit Faulheit ist.
Scott Dorman
2
Genau. Mein Punkt ist, es besteht die Gefahr, dass es abgestanden wird, ja. Aber wenn ich eine Funktion doBar () habe und nach 3 Jahren nicht "do bar", sondern "do bar and foo außer mittwochs", dann kann die Bedeutung von Funktionen auch veralten. Und Variablennamen. Aber ich hoffe, niemand nimmt dies als Grund, um Funktionen und Variablen keine aussagekräftigen Namen zu geben.
LennyProgrammers
6

Wenn der Code auf eine bestimmte Art und Weise geschrieben wurde, um ein Problem in einer Bibliothek zu vermeiden (sowohl in einer Bibliothek eines Drittanbieters als auch in einer Bibliothek, die mit dem Compiler geliefert wird), ist es sinnvoll, ihn zu kommentieren.
Es ist auch sinnvoll, Code zu kommentieren, der in zukünftigen Versionen geändert werden muss, oder wenn eine neue Version einer Bibliothek verwendet wird oder wenn beispielsweise von PHP4 auf PHP5 übergegangen wird.

kiamlaluno
quelle
6

Selbst das am besten geschriebene Buch hat wahrscheinlich noch eine Einführung und Kapitelüberschriften. Kommentare in gut dokumentiertem Code sind weiterhin nützlich, um Konzepte auf hoher Ebene zu beschreiben und die Organisation des Codes zu erläutern.

herrlich
quelle
Kommentare dieser Art geben nette visuelle Hinweise, so dass Sie nicht jede Zeile lesen müssen, um den Anfang des Abschnitts zu finden, nach dem Sie suchen. Wie mein Großvater sagte: "Alles in Maßen."
Blrfl
4

Besonders hervorzuheben ist das Anti-Pattern:

Ich habe den Eindruck, dass manchmal FLOSS-Lizenzvoreinstellungen anstelle der Dateidokumentation verwendet werden . Die GPL / BSDL macht einen schönen Fülltext, und danach sehen Sie selten einen anderen Kommentarblock.

Mario
quelle
4

Ich bin mit der Idee nicht einverstanden, dass das Schreiben von Kommentaren zur Erklärung des Codes schlecht ist. Dadurch wird die Tatsache, dass der Code Fehler enthält, völlig ignoriert. Es könnte sein , klar , was der Code tut , ohne Kommentare. Es ist weniger wahrscheinlich , dass klar sein , was der Code sollte tun. Ohne Kommentare, woher weißt du, ob die Ergebnisse falsch sind oder falsch verwendet werden?

Die Kommentare sollten die Absicht des Codes erläutern , damit jemand, der die Kommentare + den Code liest, die Chance hat, ihn zu finden, wenn ein Fehler vorliegt.

Im Allgemeinen schreibe ich Inline-Kommentare, bevor ich den Code schreibe. Auf diese Weise wird klar, wofür ich Code schreiben möchte, und es wird vermieden, dass ich mich in einem Algorithmus verliere, ohne wirklich zu wissen, was Sie tun möchten.

Danny Tuppeny
quelle
1
Unit-Tests helfen sehr, um festzustellen, ob die Ergebnisse falsch sind. Wenn Sie einen Code lesen und glauben, dass er X tut, während er in Wirklichkeit Y tut, ist der Code möglicherweise nicht lesbar genug. Ich bin nicht sicher, was Sie über die Ergebnisse bedeuten, die falsch verwendet werden. Ein Kommentar schützt Sie nicht davor, dass jemand Ihren Code auf seltsame Weise konsumiert.
Adam Lear
"Wenn Sie einen Code lesen und denken, dass er X tut, während er in Wirklichkeit Y tut" Das habe ich nicht gesagt. Ich spreche über das Verständnis , was Code tut , aber nicht , was es soll tun. Angenommen, Sie vermuten einen Fehler nach dem anderen. Woher wissen Sie, dass der Fehler "off-by-one" nicht im konsumierenden Code oder in diesem Code enthalten ist? Kommentare erklären die Absicht des Codes, was beim Aufspüren von Fehlern enorm hilft.
Danny Tuppeny
Andererseits können die Kommentare nur Aufschluss darüber geben, was der Code zum Zeitpunkt des Schreibens der Kommentare tun sollte . Der Code selbst sagt Ihnen vielleicht, was er jetzt tun soll . Kommentare werden nicht kompiliert. Sie können keine Kommentare testen. Sie können richtig oder falsch sein.
Anthony Pegram
3

Kommentare, die eingegeben werden, weil jemand der Meinung ist, dass es in Ordnung ist, 700 Zeilen in einer Methode zu haben, sind ein Geruch.

Kommentare, die vorhanden sind, weil Sie wissen, dass, wenn Sie keinen Kommentar eingeben, jemand den gleichen Fehler macht, sind ein Geruch.

Kommentare, die eingegeben werden, weil einige Code-Analyse-Tools dies erfordern, sind ebenfalls ein Geruch.

Leute, die niemals einen Kommentar abgeben oder sogar ein bisschen Hilfe für andere Entwickler schreiben, sind auch ein Geruch. Ich bin erstaunt, wie viele Leute nichts aufschreiben, sich dann aber umdrehen und feststellen, dass sie sich nicht erinnern können, was sie vor drei Monaten getan haben. Ich mag es nicht, Dokumente zu schreiben, aber ich mag es, den Leuten immer und immer wieder das Gleiche zu sagen, noch weniger.

MIA
quelle
3

Ich werde mit einer eigenen Frage antworten. Kannst du den Fehler im unkommentierten Code unten finden?

tl; dr: Die nächste Person, die Ihren Code verwaltet, ist möglicherweise nicht so gottähnlich wie Sie.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55
Ameise
quelle
Aber verwenden Sie heutzutage keine Hochsprache?
Ian
2
@ Ian: Das Programm ist ein IBM-PC-Bootloader. Sie können es nur in einer Assembly schreiben, da Sie die vollständige Kontrolle darüber benötigen, wo sich das Programm im RAM befindet, wo der letzte Kurzschluss angezeigt wird und einige Hardware-Interrupts auftreten. Im Ernst, besorgen Sie sich eine Kopie von NASM. Bauen Sie es zusammen, schreiben Sie es in den Bootsektor einer Diskette oder eines USB-Sticks und booten Sie es. Obwohl Sie wahrscheinlich feststellen werden, dass es aufgrund des Fehlers nicht wie erwartet funktioniert. Jetzt finde den Bug ... Unabhängig davon bin ich mir sicher, dass die Leute in 20 Jahren dasselbe von unkommentiertem Java verlangen werden.
Ant
Sicherlich könnte der Code in C oder C ++ geschrieben und die Binärdatei aus dem C-Objektcode und einem externen Tool zusammengesetzt werden.
Kevin Cline
Leider nicht. Schauen Sie sich diese Seite in CodeProject an: codeproject.com/KB/tips/boot-loader.aspx - "Hochsprachen haben nicht die erforderlichen Anweisungen". Darüber hinaus stehen Ihnen in einem Bootloader nur 512 Byte zur Verfügung. Manchmal muss man nur direkt an die Hardware kommen.
Ant
1
Wenn ich Assembler codiere, mache ich das, was alle anderen tun - kommentiere jede einzelne Zeile mit dem, was sie tut. Die betreffende Zeile hätte den Kommentar "Überprüfen Sie, ob der Buchstabe 0 ist", da der Code Zeichenfolgen mit 0-Abschluss im C-Stil verwendet. Mit diesem Kommentar ist leicht zu erkennen, dass der Code ein cmp mit 1 ausführt, was bedeutet, dass er entweder in einer Endlosschleife hängen bleibt oder Müll ausgibt, bis er eine zufällige 1 im RAM erreicht. Möglicherweise habe ich auch einen Kommentar zur Tatsache hinzugefügt, dass die Zeichenfolgen mit 0 abgeschlossen sind, was aus dem Code nicht ersichtlich ist. Gibt es so etwas wie automatisierte Komponententests für die Codierung von Baugruppen?
Ant
2

Sie müssen ein Gleichgewicht zwischen Code und Kommentaren halten ... Normalerweise versuche ich, einige Kommentare hinzuzufügen, die einen Codeblock wieder aufnehmen. Nicht weil ich den Code nicht verstehen kann (nun, das auch), sondern weil ich meinen eigenen Code schneller lesen und bestimmte Abschnitte finden kann, in denen die wichtigen Dinge passieren.

Wie auch immer, mein persönliches Kriterium ist "im Zweifelsfall Kommentar". Ich bevorzuge eine redundante Leitung als eine vollständig kryptische Leitung, die ich nicht verstehen kann. Ich kann Kommentare zu einer Codeüberprüfung nach einer Weile immer wieder entfernen (und das tue ich normalerweise).

Kommentare sind auch sehr hilfreich, wenn Sie "Vorsichtsmaßnahmen" wie "Vorsicht! Wenn das Format der Eingabe nicht ASCII ist, muss sich dieser Code ändern!" Hinzufügen.

Khelben
quelle
Können Sie erklären, was Sie unter "Kommentare, die einen Codeblock wieder aufnehmen" verstehen?
Mark C
2

Wenn ich das hier lese, erinnere ich mich an etwas, das ich vor einigen Jahrzehnten zum ersten Mal gelesen habe (aus einer längeren Liste, die durch Fotokopien aufbewahrt wurde):

Echte Programmierer schreiben keine Kommentare - wenn es schwer zu schreiben ist, sollte es schwer zu lesen sein

Ein etwas älterer Geruch hält an.

Murph
quelle
2

Ich denke, dass das Kommentieren von Code einen sehr schlechten Start ins Leben bekommt. Ich weiß nichts über diese Tage, aber als ich zum ersten Mal in der Schule Programmierunterricht bekam, bekam ich die folgenden Aufgaben: "Schreiben Sie ein Programm, das die Zahlen eins bis zehn in separaten Zeilen ausgibt. Vergewissern Sie sich, dass Sie Ihren Code kommentieren." Sie würden abgemeldet, wenn Sie keine Kommentare hinzufügen, da das Kommentieren Ihres Codes eine GUTE SACHE ist.

Aber was gibt es über einen so trivialen Prozess zu sagen? Sie schreiben also den Klassiker

i++; // add one to the "i" counter.

Nur um eine anständige Note zu bekommen und, wenn Sie überhaupt eine Note haben, sofort eine sehr geringe Meinung zu Code-Kommentaren zu bilden.

Das Kommentieren von Code ist keine gute Sache. Es ist manchmal notwendig, und Thomas Owens in der oberen Antwort gibt eine hervorragende Erklärung für die Situationen, in denen es notwendig ist. Diese Situationen tauchen jedoch selten bei Hausaufgaben auf.

In vielerlei Hinsicht sollte das Hinzufügen eines Kommentars als letzte Wahl angesehen werden, wenn das, was gesagt werden muss, in den aktiven Teilen der Programmiersprache nicht klar gesagt werden kann. Obwohl die Benennung von Objekten veraltet sein kann, können verschiedene Mechanismen für das Fehlen von Rückmeldungen durch Mensch und Computer dazu führen, dass das Verwalten von Kommentaren leicht vergessen wird und Kommentare daher viel schneller veraltet sind als aktiver Code. Aus diesem Grund sollte, wenn eine Auswahl möglich ist, eine Änderung des Codes zur Verdeutlichung immer der Kommentierung von unklarem Code vorgezogen werden.

Alohci
quelle
+1 für den Hinweis, dass schlechte Kommentargewohnheiten mit frühen Programmierkursen beginnen. -1 für den Schluss, dass Kommentare nur die letzte Wahl sind.
AShelly
1

Natürlich sind Kommentare ein Codegeruch ...

Jeder Programmierer weiß, dass wir alle irgendwann wahnsinnig werden, weil wir viel arbeiten, debuggen oder einfach nur verrückt sind.

"Mach das!" Ihr Projektmanager sagt.

Sie antworten: "Das geht nicht."

Sie sagen: "Dann werden wir jemanden finden, der das macht."

Sie sagen: "OK, vielleicht kann es gemacht werden."

Und dann verbringe die nächsten X Tage, Wochen, Monate damit, es herauszufinden. Während des gesamten Prozesses werden Sie versuchen und scheitern und versuchen und scheitern. Das machen wir alle. Die wahre Antwort ist, dass es zwei Arten von Programmierern gibt, die kommentieren und die nicht.

1) Diejenigen, die dies tun, vereinfachen entweder ihre Arbeit, indem sie dies zur späteren Bezugnahme dokumentieren, fehlerhafte Routinen auskommentieren, die nicht funktionierten (der Geruch löscht sie nicht, nachdem sie die funktionierende gefunden haben.), Oder indem sie den Code mit Kommentaren auflösen Formatierung hoffentlich macht es ein wenig einfacher zu lesen oder zu verstehen. Im Ernst, ich kann ihnen keine Vorwürfe machen. Aber am Ende schnappen sie und dann haben Sie Folgendes: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Diejenigen, die sich nicht als Superhelden ausgeben oder in einer Höhle leben . Sie haben einfach rücksichtslose Missachtung für andere selbst und könnten sich weniger um den Code kümmern, oder welche Bedeutung er möglicherweise für später haben könnte.

Verstehen Sie mich jetzt nicht falsch. Selbstdokumentierende Variablen und Funktionen können dies vollständig vermeiden. Und vertrauen Sie mir, dass Sie nie genug Code bereinigen können. Aber die einfache Wahrheit ist, dass Sie IMMER Kommentare löschen können, solange Sie Backups aufbewahren .

Talvi Watia
quelle
1
Antwort auf 1. Der wahre Geruch in kommentierten Routinen ist, dass sie nicht sofort gelöscht werden, wenn Sie entscheiden, dass sie möglicherweise Sackgassen sind und etwas anderes ausprobieren möchten. Dies liegt daran, dass sie in der Versionskontrolle verfügbar sein sollten, wenn Sie sie erneut aufrufen möchten .
Sharpie
1

Ich würde argumentieren, dass die Nichtverwendung einiger Kommentare in Ihrem Code ein Codegeruch ist. Ich bin damit einverstanden, dass Code so weit wie möglich selbstdokumentierend sein sollte, aber Sie erreichen einen bestimmten Punkt, an dem Code angezeigt wird, der keinen Sinn ergibt, unabhängig davon, wie gut der Code geschrieben ist. Ich habe Code in Geschäftsanwendungen gesehen, in denen die Kommentare so ziemlich obligatorisch sind, weil:

  1. Sie müssen von Fall zu Fall etwas tun, und es gibt keine gute Logik dafür.
  2. Der Code wird sich wahrscheinlich in ein oder zwei Jahren ändern, wenn die Gesetze geändert werden und Sie ihn schnell wiederfinden möchten.
  3. Jemand hat den Code in der Vergangenheit bearbeitet, weil er nicht verstand, was der Code tat.

Darüber hinaus können die Style-Guides eines Unternehmens Sie auffordern, bestimmte Schritte auszuführen. Wenn sie angeben, dass Sie Kommentare zu den Codeblöcken in einer Funktion haben sollten, schließen Sie die Kommentare ein.

rjzii
quelle
1

Es gibt einen großen grundsätzlichen Unterschied zwischen Kommentaren und Code: Kommentare sind eine Möglichkeit für Leute, Ideen an andere Leute zu kommunizieren, während Code hauptsächlich für den Computer gedacht ist. Es gibt viele Aspekte in "Code", die auch nur für Menschen gelten, wie Benennung und Einrückung. Aber Kommentare werden ausschließlich für Menschen von Menschen geschrieben.

Deshalb ist das Schreiben von Kommentaren genauso schwierig wie jede schriftliche menschliche Kommunikation! Der Autor sollte eine klare Vorstellung davon haben, wer das Publikum ist und welche Art von Text er benötigt. Wie können Sie wissen, wer Ihre Kommentare in zehn, zwanzig Jahren lesen wird? Was ist, wenn die Person aus einer völlig anderen Kultur stammt? Ich hoffe, jeder versteht das.

Selbst in der kleinen homogenen Kultur, in der ich lebe, ist es so schwierig, anderen Menschen Ideen zu vermitteln. Die menschliche Kommunikation scheitert normalerweise, außer aus Versehen.

user15127
quelle
0

Ich muss Ihrem Kollegen zustimmen. Ich sage immer, wenn ich meinen Code kommentiere, bedeutet das, dass ich mir Sorgen mache, dass ich meinen eigenen Code in Zukunft nicht mehr herausfinden kann . Das ist ein schlechtes Zeichen.

Der einzige andere Grund, warum ich Kommentare in den Code streue, besteht darin, etwas aufzurufen, das keinen Sinn zu ergeben scheint.

Diese Kommentare haben normalerweise die Form von:

//xxx what the heck is this doing??

oder

// removed in version 2.0, but back for 2.1, now I'm taking out again
Ken
quelle
1
Alternativ kann der Kommentar die Tatsache widerspiegeln, dass der Code einen komplexen Algorithmus adressiert, bei dem der Code von Natur aus nicht offensichtlich ist, oder dass der Code aufgrund von Faktoren, die außerhalb Ihrer Kontrolle liegen (z. B. Interaktion mit einem externen Dienst), etwas Seltsames tut.
Murph
Sehr richtig. Es gibt Gründe, warum guter Code möglicherweise nicht offensichtlich ist. Die meiste Zeit ist verwirrender Code verwirrend, weil er verschleiert geschrieben ist.
Ken
Scheint, als hätten Sie keinen Code für eingebettete Prozessoren geschrieben, in denen Sie nur 32 KB zum Spielen haben, und Dinge, die Ihnen ein Gebot erschweren. Kommentare sind Lebensretter.
quick_now
0

Codekommentare, die gegebenenfalls Einheiten von Funktionsargumenten und Rückgaben, Strukturfelder und sogar lokale Variablen angeben, können sehr praktisch sein. Erinnere dich an den Mars Orbiter!

dmuir
quelle
Es ist viel besser, die Einheiten in die Variablennamen zu integrieren, damit sich der arme Programmierer nicht daran erinnern muss. Anstelle von 'doppelte Länge // in Metern' sagen Sie 'doppelte Länge_m'. Am besten ist es, eine mächtigere Sprache zu verwenden, also kann man einfach Länge l sagen; Kraft f; Drehmoment t = 1 * f; print (t.in (Torque.newtonMeter));
Kevin Cline
0

Hier ist meine Faustregel:

  • Schreiben Sie den Code und speichern Sie eine kurze Zusammenfassung des Codes in einem separaten Dokument.
  • Lassen Sie den Code einige Tage in Ruhe, um an etwas anderem zu arbeiten.
  • Kehren Sie zum Code zurück. Wenn Sie nicht sofort verstehen können, was es tun soll, fügen Sie die Zusammenfassung der Quelldatei hinzu.
Maxpm
quelle
0

Nein, Kommentare sind kein Code-Geruch, sie sind nur ein Werkzeug, das missbraucht werden kann.

Beispiele für gute Kommentare:

// Ich denke das ist in cm. Weitere Untersuchung erforderlich!

// Dies ist eine clevere Art, X zu machen

// Die Liste ist hier garantiert nicht leer

Andres F.
quelle
Der dritte ist ein schlechter Kommentar IMO. Warum nicht Assert(list.IsEmpty)?
CodesInChaos
@CodeInChaos IMO Assert(!list.isEmpty())ist nicht genau ein Vertrag wie im dritten Kommentar, sondern einfach ein Verhalten (dh "IllegalArgumentException auslösen, wenn das Argument leer ist"), das wie jede andere Programmlogik Unit-getestet werden muss. Beachten Sie den feinen Unterschied zum Kommentar, der angibt, wann die Methode verwendet werden kann, aber kein Verhalten angibt, wenn die Vorbedingung nicht erfüllt ist. Noch besser als der Kommentar wäre es, Verträge zur Kompilierungszeit durchzusetzen. Aber das übersteigt den Rahmen meiner Antwort;)
Andres F.
Sie sollten nicht in der Lage sein, Asserts zu üben , da sie Dinge beschreiben, die niemals passieren sollten, selbst wenn die öffentliche API ungültige Argumente empfängt.
CodesInChaos
@CodeInChaos Ich widerrufe meine Meinung. Hier ist , was Sunacle über Behauptungen zu sagen hat . Anscheinend hattest du recht. Du lernst jeden Tag etwas!
Andres F.