"Kommentare sind ein Code-Geruch" [geschlossen]

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

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.

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.

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)

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.

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.

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.

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

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:

• Entschuldigung im Code
• Kommentare benötigen

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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 .

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.

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.

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

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!

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.

Informieren Sie Ihren Kollegen über die Techniken der Literatenprogrammierung .

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