it-swarm-eu.dev

"Kommentare sind ein Code-Geruch"

Ein Mitarbeiter von mir glaubt, dass jede Verwendung von In-Code-Kommentaren (dh keine Methode im Javadoc-Stil oder Klassenkommentare) ein Code-Geruch) ist . Was denken Sie?

100
Fishtoaster

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 jedenfalls hoffen, dass alle 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, zu verfolgen, was Ihr Code tut. 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, dass jemand anderes (oder mehrere andere Personen), der mit der Implementierungssprache und dem Projekt vertraut ist, Ihren Code betrachtet. Wenn er nicht sowohl das Warum als auch das Wie verstehen kann, sollten Sie sowohl das Warum als auch das Warum kommentieren das wie.

Was im Code jedoch 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 haben, der erklärt, warum Sie die von Ihnen getroffenen Entscheidungen getroffen haben. Ich würde vermuten, dass Sie möglicherweise erst nach einer Codeüberprüfung feststellen, dass ein Kommentar erforderlich ist, wenn die Leute wissen möchten, warum Sie X anstelle von Y ausgeführt haben. Sie können Ihre Antwort im Code für alle anderen Personen erfassen, die sie betrachten 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 dahingehend aktualisieren, warum Sie Algorithmus X über Y gewählt haben. Veraltete Kommentare sind ein noch größerer Codegeruch.

167
Thomas Owens

Das ist im Moment besonders irritierend zu hören. Ich habe dieses Wochenende einige Zeit damit verbracht, mir sehr gut benannten, sehr sauberen, unkommentierten Code anzusehen, der einen Forschungsalgorithmus implementiert (einen, der eigentlich nicht veröffentlicht wird). Ich bin auf hohem Niveau damit vertraut, der Typ neben mir war der Erfinder, und der Code wurde vor einigen Jahren von jemand anderem geschrieben. Wir könnten kaum ihm folgen.

Ihr Mitarbeiter ist offensichtlich nicht erfahren genug.

110
Paul Nathan

Kommentare sollten erklären, warum, nicht wie.

Kommentare vom Typ How werden normalerweise 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)
75
Sam Saffron

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

Obsessives Kommentieren ist schlecht und bereitet Wartungsprobleme, und Kommentare sind kein Ersatz für gut benannte Methoden, Klassen, Variablen usw. Aber manchmal auch Putten warum Etwas ist so, wie es ist, kann für den armen Idioten, der den Code in sechs Monaten pflegen muss, immens wertvoll sein - besonders wenn dieser arme Idiot Sie ist.

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.

32
BlairHippo

Im Idealfall sollte der Code so gut codiert sein, dass er automatisch erklärt werden kann. In der realen Welt wissen wir, dass auch Code von sehr hoher Qualität 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 jedoch eine gute Hilfe für die Lesbarkeit des Codes sein:

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

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

29
Wizard79

Das kategorische Definieren einer Methode oder eines Prozesses als "Codegeruch" ist ein "Eiferergeruch". Der Begriff wird zum neuen "als schädlich angesehen".

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

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

Persönlich verwende ich sehr wenige Kommentare. Erläutern Sie den Zweck nicht offensichtlicher Prozesse und überlassen Sie die gelegentliche Morddrohung jedem, der erwägt, Dinge selbst zu ändern, die wochenlanges Tuning erfordern.

Alles neu zu gestalten, bis ein Kindergärtner verstehen kann, dass es wahrscheinlich keine effiziente Nutzung Ihrer Zeit ist und wahrscheinlich nicht so gut funktioniert wie eine präzisere Version.

Kommentare wirken sich nicht auf die Laufzeit aus. Das einzige negative Problem ist die Wartung.

26
Bill

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

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

Dies ist nicht die Bedeutung des Begriffs!

Die Code-Geruchsmetapher stammt von Wards Wiki und sie betonen:

Beachten Sie, dass ein CodeSmell ein Hinweis darauf ist, dass etwas nicht stimmt, keine Gewissheit. Eine vollkommen gute Sprache kann als CodeSmell angesehen werden, weil sie häufig missbraucht wird oder weil es eine einfachere Alternative gibt, die in den meisten Fällen funktioniert. Etwas als CodeSmell zu bezeichnen, ist kein Angriff. Es ist einfach ein Zeichen dafür, dass ein genauerer Blick angebracht 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 darauf, dass etwas verbessert werden könnte." Vielleicht können Sie eine Variable umbenennen, die "Extraktionsmethode" -Refactoring durchführen - oder vielleicht ist der Kommentar tatsächlich die beste Lösung.

Das bedeutet, dass Kommentare Code-Gerüche sind.

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

23
Rasmus Faber

In einigen Fällen kann keine gute 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 seltsam aus, nicht wahr? Wahrscheinlich ein Copy-Paste-Fehler? Schreie 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
23
user281377

Ich denke, die Regel ist ganz einfach: Stellen Sie sich einen völlig Fremden vor, der Ihren Code sieht. Sie werden wahrscheinlich in 5 Jahren ein Fremder in Ihrem eigenen Code sein. Versuchen Sie, die mentale Anstrengung zu minimieren, um Ihren Code für diesen Fremden zu verstehen.

21

Eine gute Idee, um die richtigen Kommentare zu haben, ist, mit dem Schreiben von Kommentaren zu beginnen.

// 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 Methoden einfach extrahieren, um sogar die Kommentare zu entfernen.
lass den Code diese Dinge einfach sagen! Sehen Sie, wie dies auf sehr schöne Weise umgeschrieben wird (Ausschneiden/Einfügen):

// 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 ein nützlicher Weg, um das Kommentieren auf ein Minimum zu beschränken. Es ist wirklich nutzlos, jede Zeile zu kommentieren ... Dokumentieren Sie nur eine einzelne Zeile, wenn es sich um eine magische Wertinitialisierung handelt oder wenn dies sinnvoll ist.

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

11
Tamara Wijsman

Ich denke, die Antwort ist die übliche "Es kommt darauf an". Das Kommentieren von Code nur zum Kommentieren von Code ist ein Geruch. Das Kommentieren von Code, weil Sie einen obskuren Algorithmus verwenden, der eine Größenordnung schneller ist, spart dem Wartungsprogrammierer (normalerweise 6 Monate nach dem Schreiben) einen halben Tag, um den Code zu durchsuchen und festzustellen, was er tut.

10
Brandon
// 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.
10
Zzz

Codekommentare sind definitiv kein "Codegeruch". Diese Überzeugung beruht normalerweise 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 Weise etwas tut, können (und sind normalerweise) für die Wartung wichtig sein.

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 diesen Code später ansehen oder wenn jemand anderes 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 schreiben, sollten Sie Ihr Bestes tun, um den Zweck des Codes (das Warum, nicht das Wie) zu dokumentieren und die Gründe und die 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ückgehen und sie hinzufügen.

Sams bringt sich in 24 Stunden Visual C # 2010 bei , S. 348-349.

8
Scott Dorman

Wenn der Code auf eine bestimmte Weise geschrieben wurde, um ein Problem in einer Bibliothek zu vermeiden (sowohl eine Bibliothek eines Drittanbieters als auch eine 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 Sie beispielsweise eine neue Version einer Bibliothek verwenden oder wenn Sie von PHP4 zu PHP5 wechseln.

6
kiamlaluno

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.

6
munificent

Von lobenswerter Erwähnung ist das Anti-Muster:

Ich habe den Eindruck, dass manchmal häufig FLOSS-Lizenzvorverstärker verwendet werden anstelle von der Dateidokumentation. Die GPL/BSDL erstellt einen schönen Fülltext, und danach sehen Sie selten einen anderen Kommentarblock.

4
mario

Ich bin nicht einverstanden mit der Idee, dass das Schreiben von Kommentaren zur Erklärung des Codes schlecht ist. Dies ignoriert völlig die Tatsache, dass Code Fehler aufweist. Es könnte klar sein, was der Code ohne Kommentare tut . Es ist weniger wahrscheinlich, dass klar ist, was der Code tun soll . Woher wissen Sie ohne Kommentare, ob die Ergebnisse falsch sind oder falsch verwendet werden?

Die Kommentare sollten die Absicht des Codes erklären, 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 weniger verloren, in einem Algorithmus verloren zu gehen, ohne wirklich zu wissen, was Sie tun möchten.

4
Danny Tuppeny

Ich werde mit einer eigenen Frage antworten. Können Sie 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
3
Ant

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 da sind, weil Sie wissen, dass jemand den gleichen Fehler macht, wenn Sie keinen Kommentar eingeben, ist ein Geruch.

Kommentare, die eingegeben wurden, weil einige Code-Analyse-Tools verlangen, dass es auch ein Geruch ist.

Leute, die nicht jemals einen Kommentar abgeben oder auch nur ein wenig Hilfe für andere Entwickler schreiben, sind ebenfalls ein Geruch. Ich bin erstaunt, wie viele Leute nicht aufschreiben, sondern sich dann umdrehen und anerkennen, dass sie sich nicht erinnern können, was sie vor 3 Monaten getan haben. Ich schreibe nicht gerne Dokumente, aber ich möchte den Leuten immer und immer wieder das Gleiche sagen müssen, noch weniger.

3
MIA

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 (na ja, das auch), sondern weil ich meinen eigenen Code schneller lesen und bestimmte Abschnitte finden kann, in denen die wichtigen Dinge geschehen.

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

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

2
Khelben

Ich denke, dass das Kommentieren von Code einen sehr schlechten Start ins Leben hat. Ich weiß nichts über diese Tage, aber als ich zum ersten Mal in der Schule Programmieren lernte, bekam ich Aufgaben von der Art "Schreiben Sie ein Programm, das die Zahlen eins bis zehn in separaten Zeilen druckt. Stellen Sie sicher, dass Sie Ihren Code kommentieren." Sie würden markiert, wenn Sie keine Kommentare hinzufügen würden, da das Kommentieren Ihres Codes eine gute Sache ist.

Aber was gibt es über einen so trivialen Prozess zu sagen? Am Ende schreibst du also den Klassiker

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

nur um eine anständige Note zu bekommen und, wenn Sie überhaupt eine haben, sofort eine sehr geringe Meinung über Codekommentare zu bilden.

Code-Kommentare sind keine gute Sache. Es ist manchmal eine notwendige Sache, und Thomas Owens in der oberen Antwort bietet eine ausgezeichnete Erklärung der Situationen, in denen es notwendig ist. Diese Situationen treten jedoch selten bei Hausaufgaben auf.

In vielerlei Hinsicht sollte das Hinzufügen eines Kommentars als letzter Ausweg betrachtet 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 zur fehlenden Rückmeldung von Mensch und Computer leicht vergessen, Kommentare zu pflegen, und folglich werden Kommentare viel schneller veraltet als aktiver Code. Aus diesem Grund sollte, wenn eine Auswahl möglich ist, das Ändern des Codes zur Verdeutlichung immer dem Kommentieren von unklarem Code mit Kommentaren vorgezogen werden.

2
Alohci

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

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

Ein etwas älterer Geruch denkt nach.

2
Murph

Natürlich sind Kommentare ein Code-Geruch ...

jeder Programmierer weiß, dass wir alle irgendwann verrückt werden aufgrund der Menge an Arbeit, Debugging oder einfach nur Wahnsinn, dem wir begegnen.

"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 getan 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. Wir alle tun dies. Die wahre Antwort ist, dass es zwei Arten von Programmierern gibt, diejenigen, die Kommentare abgeben, und diejenigen, die dies nicht tun.

1) Diejenigen, die dies tun, erleichtern entweder ihre eigene Arbeit, indem sie zur späteren Bezugnahme dokumentieren, fehlgeschlagene Routinen auskommentieren, die nicht funktionierten (der Geruch löscht sie nicht, nachdem sie die funktionierende gefunden haben) oder den Code mit Kommentaren auflösen Formatierung auf hoffentlich erleichtert das Lesen oder 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 entweder nicht vorgeben, ein Superheld zu sein, oder leben in einer Höhle . 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.

Versteh mich jetzt nicht falsch. Selbstdokumentierende Variablen und Funktionen können dies vollständig vermeiden. Und vertrau mir Sie können nie genug Code bereinigen. Aber die einfache Wahrheit ist, dass Sie, solange Sie Backups aufbewahren, [~ # ~] immer [~ # ~] Kommentare löschen können.

1
Talvi Watia

Es gibt einen großen grundlegenden Unterschied zwischen Kommentaren und Code: Kommentare sind eine Möglichkeit für Menschen, Ideen an andere Menschen weiterzugeben, 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 das Benennen und Einrücken. Aber Kommentare werden ausschließlich für Menschen von Menschen geschrieben.

Das Schreiben von Kommentaren ist daher 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, Ideen an andere Menschen weiterzugeben. Die menschliche Kommunikation schlägt normalerweise fehl, außer durch Zufall.

1
user15127

Ich würde argumentieren, dass die Nichtverwendung von einigen Kommentaren in Ihrem Code ein Codegeruch ist. Ich stimme zu, dass Code so weit wie möglich selbstdokumentierend sein sollte, aber Sie erreichen einen bestimmten Punkt, an dem Sie Code sehen, der keinen Sinn ergibt, unabhängig davon, wie gut der Code geschrieben ist. Ich habe Code in Geschäftsanwendungen gesehen, in denen die Kommentare 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 verstanden hat, was der Code tut.

In Unternehmensstil-Anleitungen werden Sie möglicherweise auch aufgefordert, eine bestimmte Vorgehensweise auszuführen. Wenn sie angeben, dass Sie Kommentare haben sollten, in denen erläutert wird, welche Codeblöcke in einer Funktion ausgeführt werden, fügen Sie die Kommentare hinzu.

1
rjzii

Ich muss Ihrem Kollegen zustimmen. Ich sage immer, wenn ich meinen Code kommentiere, bedeutet das, dass ich mir Sorgen mache, dass I nicht in der Lage ist, meinen eigenen) herauszufinden Code in der Zukunft. Das ist ein schlechtes Zeichen.

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

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
0
Ken

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.
0
Maxpm

Informieren Sie Ihren Kollegen über die Literate Programming Technik.

0
SK-logic

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

0
dmuir

Nein, Kommentare sind kein Codegeruch, sondern nur ein Werkzeug, das missbraucht werden kann.

Beispiele für gut 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

0
Andres F.

Jedoch ist Code, der überhaupt nicht verstanden werden kann, ein viel größerer Code-Geruch…

Bitte geben Sie mir jedoch einen sauberen Code, an dem ich arbeiten kann
Wenn dies keine Option ist, hätte ich lieber "schmutzigen" Code mit Kommentaren
als schmutziger Code ohne Kommentare.

0
Ian

Die meisten Wörter wurden aus meinem Mund genommen. Aber ich nehme an, um alles zusammenzufassen: Der Sinn von Kommentaren besteht darin, eine allgemeine Beschreibung/Erklärung dessen zu geben, was der Code tut.

Außerdem sind hier einige Beispiele, wie ich Kommentare verwende:

  • als Überschriften, um den allgemeinen Zweck eines Codeabschnitts anzugeben
  • zu notieren, woher ich Code geschrieben habe und dadurch Plagiate zu vermeiden
  • gelegentlich an den Enden von Blöcken, um daran zu erinnern, an welchem ​​Block sie enden
  • darauf hinzuweisen, dass Code, der verdächtig aussehen kann, beabsichtigt ist (z. B. die ungeraden Zeiten, in denen ein Switch-Fall durchfällt)
  • die Mathematik hinter einem Algorithmus zu erklären
0
Stewart

Bisher hat dies niemand in diesem Thread gesagt, also werde ich:

Typnamen, Variablennamen, Funktionsnamen, Methodennamen und Kommentare sind nur Metadaten zu Ihrem Code und haben nichts mit dem vom Compiler generierten Maschinencode zu tun (außer natürlich den Namen der exportierten und Debug-Symbole).

Typ- und Variablennamen sind Ihre Substantive, Funktions- und Methodennamen sind Ihre Verben, mit denen Sie die auszuführenden Schritte beschreiben. Kommentare sind für alles andere.

Einige Beispiele:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

Kommentare können veraltet sein, wenn sie nicht aktualisiert werden, aber auch Variablen- und Funktionsnamen können veraltet sein. Ich bin kürzlich auf ein bufPtr -Feld in einer C-Struktur gestoßen, das nichts mit Puffern oder Zeigern zu tun hat. Und ich habe eine inflateBuffer -Funktion gesehen, die keine deflationierten Daten dekomprimiert, sondern eine vollständige GZIP-Datei ... Diese sind genauso ärgerlich wie veraltete Kommentare.

0
Calmarius

Es scheint nicht so, als würden zu viele Antworten das Programmieren in Teams in Betracht ziehen. Ich bin ein leitender Entwickler und neige dazu, Kommentare zu schreiben, um zu erklären, was für mich sonst einfach zu verstehen ist.

Ich sehe es als eine Form der posthumen Teamkommunikation oder -erziehung. Ich ermutige das Team, den von ihnen verwendeten Code durchzusehen, habe ihn aber möglicherweise nicht geschrieben, um ihn besser zu verstehen.

Ein paar Beispiele aus dieser Woche (PHP-Code):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

Ich hoffe, der Name PATTERN_PHOTO Wäre später im Code hilfreich, um zu erklären, was er tut, aber ohne die Kommentare, wie klar wäre es für einen Junior-Entwickler, was dieses spezielle Muster bewirkt?

Gleicher Code:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

Es besteht die Erwartung, dass unsere Entwickler PHP kennen, aber nicht, dass sie das Linux-Betriebssystem verstehen, das wir für das Hosting verwenden.

Ich finde, dass diese Kommentare die Gesamteffizienz unseres Teams für die sehr kurze Zeit, die zum Schreiben benötigt wird, tatsächlich steigern.

  • Es gibt weniger Fälle, in denen Leute Code neu schreiben, nur weil sie nicht verstehen, wie es funktioniert. "Ich habe nicht verstanden, wie es das tat, was es sollte, also habe ich es repariert." Im Ernst, ich musste mich vorher damit befassen.
  • Es werden weniger Fragen zu einzelnen Codeteilen gestellt. Um die Fragen nur einmal zu beantworten, muss ich normalerweise den Code nachschlagen und Zeit haben, mich mit ihm vertraut zu machen. Und manchmal bekomme ich die gleiche Frage von mehr als einer Person im Abstand von Wochen. (Ja, es wäre so einfach wie in den obigen Beispielen)
  • Andere Entwickler werden ermutigt und angeleitet, selbstständig zu lernen. Ich würde erwarten, dass sie, wenn sie auf //Ignore . and .. directories in Linux Stoßen würden, wahrscheinlich auf Google hüpfen und Linux plötzlich ein bisschen besser verstehen würden.
0
Chris