it-swarm.dev

Selbstdokumentierender Code Vs. Kommentierter Code

Ich hatte eine Suche, habe aber nicht gefunden, wonach ich gesucht habe. Sie können mich gerne verlinken, wenn diese Frage bereits gestellt wurde.

Anfang dieses Monats wurde dieser Beitrag verfasst:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Um es zusammenzufassen, Sie sind ein schlechter Programmierer, wenn Sie keine Kommentare schreiben. Meine persönliche Meinung ist, dass Code beschreibend sein sollte und meistens keine Kommentare erfordert, es sei denn, der Code kann nicht selbstbeschreibend sein.

Im gegebenen Beispiel

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Der Autor sagte, dass dieser Code einen Kommentar erhalten sollte, meine persönliche Meinung ist, dass der Code ein Funktionsaufruf sein sollte, der beschreibend ist:

$extension = GetFileExtension($image_filename);

In den Kommentaren machte jedoch tatsächlich jemand genau diesen Vorschlag:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-3571

Der Autor antwortete, der Kommentator sei "einer dieser Leute", d. H. Ein schlechter Programmierer.

Wie sehen alle anderen den selbstbeschreibenden Code im Vergleich zum kommentierenden Code?

22
Phill

Ich schreibe lieber selbstdokumentierenden Code. Eine Anleitung hierfür ist Clean Code .

Dies bedeutet natürlich nicht, dass man niemals Kommentare verwenden sollte - sie haben ihre Rolle, aber meiner Meinung nach sollten Sie sie sorgfältig verwenden. Diese frühere Antwort von mir auf SO erklärt meine Gedanken zu diesem Thema ausführlicher.

Natürlich lohnt es sich, wie @Niphra feststellte, immer noch einmal zu überprüfen, ob das, was ich für sauber halte, für andere wirklich verständlich ist. Dies ist jedoch auch eine Frage der Praxis. Zurück in der Uni habe ich kryptische Codeteile geschrieben, einfach weil ich nach meiner Laune seltsame und lustige Namen für alle Code-Entitäten verwendet habe. Bis mein Lehrer eine meiner Aufgaben zurückwarf und höflich feststellte, dass er nicht herausfinden konnte, welches Modul das Hauptmodul war :-) Das war eine gute Lektion, also bemühte ich mich, mich darauf zu konzentrieren, seitdem immer besser lesbaren Code zu schreiben. Heutzutage bekomme ich kaum Beschwerden von Teamkollegen.

47
Péter Török

Sie sollten nicht dokumentieren, was der Code tut, aber Sie sollten dokumentieren, warum er es tut.

Keine Menge an Benennungstricks enthüllt das Warum und Warum, daher müssen Sie Kommentare hinzufügen, um den Zweck der verschiedenen Codebits zu erläutern.

Alle anderen Kommentare können sicher entfernt werden.

66
biziclop

Ich glaube eigentlich nicht an selbstbeschreibenden Code. Es gibt besser lesbaren Code und weniger lesbarer Code , abhängig von der Sprache, Ihren Kenntnissen (als Originalautor), den Kenntnissen des Lesers, und die Codefunktion. Aber nein, trotzdem ... sollte es mit einem kurzen Kommentar beschrieben werden.

Was mir jetzt klar ist, dass ich in diesem Bereich des Denkens bin , wird mir in einem Jahr, in dem ich denke, wahrscheinlich nicht klar sein über etwas völlig anderes und müssen diesen Teil des Codes erneut verwenden.

Kommentieren Sie also Ihren Code. Natürlich nicht jede Zeile (Himmel, nein), aber ein paar Kommentarzeilen über einer Funktion/Unterroutine/einem Modul oder einem besonders kniffligen Teil und kurz erzählen, was es tut. Sie werden sich in ein oder zwei Jahren bedanken.

38
Rook

Glücklicherweise sind beide Lager in dieser Diskussion hier vertreten, und es wurden Vor- und Nachteile für beide erwähnt.

Ich glaube, beide Lager haben überlappende Argumente und stimmen in den meisten von ihnen überein. Nur die Art und Weise, wie man sie erreicht, ist etwas anders.

Überlappende Argumente

  • Code sollte lesbar sein.
  • Kommentare sollten nicht genau dasselbe sagen wie der Code, sondern bei Bedarf weitere Einblicke geben.
  • Alle Variablen-/Funktionsnamen sollten gut überlegt sein, damit sie gut darstellen, was sie sind/tun.
  • Doppelter Code sollte verhindert werden.

Der Hauptunterschied besteht nun darin, wie viel Gewicht auf einige dieser Argumente gelegt wird.

Selbstbeschreibender Code

  • Kommentare können veraltet sein. Minimieren Sie daher deren Verwendung, da falsche Kommentare schlechter sind als keine Kommentare.
  • Kommentare sind eine Vervielfältigung des Codes. Alles, was in Code geschrieben werden kann, sollte in Code geschrieben werden.

Weitere Kommentare

  • Kommentare sind besser lesbar als Code. Normales Englisch kann etwas besser beschreiben.

  • Einfacher Code führt häufig zu Mehrdeutigkeiten, die ohnehin kommentiert werden müssen. Der Versuch, dies im Code zu beschreiben, führt zu zu langen Namen. Darüber hinaus sind Sie ständig mit diesen „zusätzlichen“ Informationen konfrontiert, die Sie nur benötigen, wenn Sie zum ersten Mal darauf stoßen.

Ich glaube, beide Lager haben sehr gültige Argumente, aber Sie sollten einem Lager nicht hektisch folgen, nur weil es ein Problem löst.

Um zu demonstrieren, wird Code in dem Buch Clean Code in zahlreiche kleinere Methoden unterteilt, die nur einmal aufgerufen werden. Methoden werden nur aus dem Grund erstellt, um den Code zu dokumentieren (und TDD zu vereinfachen). Dies führt zu Function Hell . Der Code ist weniger lesbar als ursprünglich, und während des Refactorings wurde nicht daran gedacht, wiederverwendbaren Code zu kapseln.

Auf der anderen Seite sehen Sie häufig APIs, in denen jede Funktion kommentiert wird, nur weil "Kommentare gut sind". Die Dinge, die hätten kommentiert werden sollen, sind es immer noch nicht.

19
Steven Jeuris

"Es tut mir leid, aber du bist dieser Typ."

Ich frage mich, warum er nicht gerne kommentiert: P.

Im Ernst, Codierung ist zu viel Kunst, als dass man wahrheitsgemäß eine so umfassende Aussage machen könnte. Manchmal braucht man Kommentare, manchmal mehr und besser benannte Funktionen. Normalerweise beides.

Lesen Sie die Alphabetisierung als extremen Stil.

5
vegai

Die kurze, bessere und richtige Antwort

Die Idee, dass gut geschriebener, "selbstdokumentierter Code" alles ist, was Sie brauchen, ist ein Anti-Pattern und sollte sterben, sogar wenn Ausnahmen für Kommentare gemacht werden, die "warum" erklären. Es ist ein Mythos, dass Sie immer den gesamten Code für jeden Algorithmus so klar schreiben können, dass jeder Programmierer einen Blick darauf werfen und ihn abrufen kann (oder dass kein Refactoring oder keine organisatorische Zeit erforderlich ist). Noch wichtiger ist, dass Programmierer, die denken sie klaren Code schreiben, dies meistens nicht tun.

Eine viel bessere Antwort als Kommentare sollten nur verwendet werden, um das "Warum" zu erklären ist, dass Kommentare:

  • erkläre "warum" (natürlich)
  • erklären Sie "was" in einzelnen Zeilen nur, wenn der Code komplex ist oder der Zweck unklar ist und es nicht möglich oder nicht wert ist, weiter vereinfacht zu werden
  • erklären Sie "Was" für Codeblöcke, um das Verständnis zu beschleunigen und das zu finden, was Sie benötigen

Die Erklärung zum Sichern

Die Leute denken fälschlicherweise, dass der einzige Grund, warum Leute Kommentare verwenden, darin besteht, zu erklären, was eine Codezeile bedeutet. Die Wahrheit ist ein großer Zweck des Kommentierens von Code ist es, ihn schneller zu machen, um durch Ihren Code zu blicken und zu finden, wonach Sie suchen. Wenn ich später zum Code zurückkomme oder den Code eines anderen lese, kann ich natürlich einen Abschnitt gut geschriebenen Codes lesen und verstehen - aber ist es nicht schneller und einfacher, den Kommentar oben zu lesen, in dem steht, was dieser Codeabschnitt tut und Überspringen Sie es insgesamt, wenn es nicht das ist, wonach ich suche? Warum überhaupt dort sitzen und Code herausfinden, auch wenn er gut geschrieben ist, wenn Sie sich ein paar Kommentare ansehen und eine ganze Funktion verstehen können? Deshalb verwenden wir beschreibende Namen für Funktionen - niemand sagt, dass ich keinen beschreibenden Namen für meine Funktion verwenden muss, weil jemand einfach meinen sauber geschriebenen Code durchsehen kann, um zu sehen, was er tut.

Wenn ich zum Beispiel die Funktion einer anderen Person durchschaue, ist es einfacher, Zeile für Zeile durch den Code zu gehen, um zu sehen, was er tut, oder drei gut geschriebene Kommentare in der gesamten Funktion zu lesen, um genau zu sehen, was die Funktion tut und wo es macht es?

Ein weiteres Anti-Pattern ist die Überbeanspruchung von Funktionen zum Kommentieren Ihres Codes. Gut benannte Funktionen sind ein wichtiger Bestandteil der Codedokumentation, aber manchmal trennen Programmierer 2-3 Codezeilen, die nirgendwo anders verwendet werden, zu Dokumentationszwecken in eine Funktion. Warum ist eine Überbeanspruchung von Funktionen besser als eine Überbeanspruchung von Kommentaren? Die Verwendung solcher Funktionen ist dasselbe wie das Umarmen von GOTO-Anweisungen - es wird Spaghetti-Code erstellt, dessen Befolgung schwierig sein kann.

Wenn Sie in einer Unternehmensumgebung arbeiten, in der ständig Code geteilt wird und die Leute nicht immer die Zeit haben, ihren Code zu perfektionieren, können ein paar gute Kommentare viel Zeit und Frust sparen. Und denken Sie daran, während Sie vielleicht ein Guru sind, der Code mit Lichtgeschwindigkeit lesen kann, ist dies wahrscheinlich nicht jeder in Ihrem Büro.

3
dallin

Nun, Sie müssen sich auch an etwas erinnern, das für Sie offensichtlich oder "selbstdokumentierend" ist, möglicherweise nicht für jemand anderen ... Vielleicht für jemanden, der bestimmte Funktionen weniger versteht. Also kommentiere ich so ziemlich alles.

2
user6791

Nun, die Sache mit selbstdokumentierendem Code ist, dass Sie innerhalb dieser Funktion Folgendes finden würden:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

dies ist selbsterklärend, wenn Sie den Funktionsnamen haben, da er nur aus zwei Zeilen besteht. Wenn die Dinge komplizierter werden, müssen Sie entweder alle paar Codezeilen in eine Funktion mit einem beschreibenden Namen einschließen oder Kommentare verwenden falls erforderlich.

Ich habe nie verstanden, warum es eine oder/oder Angelegenheit sein sollte, anstatt und/und. Ja, machen Sie Ihren Code so selbstdokumentierend wie möglich, und fügen Sie den Teilen einige Kommentare hinzu, die sonst eher unklar wären.

2
Joris Meys

Kommentare und der selbst dokumentierte Bereinigungscode sind unterschiedlich. Bei Code dreht sich alles um wie Dinge zu tun. Und Kommentare sollten den warum Teil abdecken, der unabhängig von Ihrer Sprache nicht im Code erklärt werden kann. Wenn Ihre Sprache sehr eingeschränkt ist und Sie keine Verträge, keine statischen Spezifikationen und sogar keine Behauptungen haben, sollten Kommentare die Grenzprobleme Ihres Codes abdecken.

2
SK-logic

In diesem Fall ist es einfach, eine beschreibende Funktion zu erstellen. Aber ich habe viel Code gelesen, der von guten Programmierern erstellt wurde, die glaubten, ihr Code sei selbstdokumentierend, und was für sie kristallklar war, war für mich wirklich verwirrend.

$ extension = GetFileExtension ($ image_name);

Kann ich eine Reihe von Bildnamen senden, um zu Ihrem Beispiel zurückzukehren, oder wird nur ein Bild aufgenommen? Unterstützt es Dateitypen oder nur einige davon? Wird es mir die Saite sichern oder muss ich es tun? Wenn der Dateityp nicht vorhanden ist, benachrichtigt er mich?

Natürlich dehne ich das ein bisschen. Aber ich erinnere mich an einen Programmierer, der glaubte, audio_bandwidth und video_bandwidth seien selbstdokumentierende Namen. Es stellte sich heraus, dass Audio in Bytes und Video in Kilobyte ausgedrückt werden musste. Es hat viel Zeit gekostet, das herauszufinden.

1
DistantEcho

Das eine schließt das andere nicht aus. Obwohl Ihr Code selbst kommentiert ist, benötigen Sie manchmal regelmäßige Kommentare, um zu erklären warum Ihr selbstkommentierender Code macht das, was er tut.

1
gablin

Ich bin mit diesem Artikel nicht einverstanden und stimme Ihnen in gewissem Maße zu. Wenn Sie gute Methodennamen, gute Variablennamen und kleine Methoden verwenden, die eine einzige Aufgabe erfüllen, sollte der Code einfach zu befolgen sein.

Versuchen Sie einfach, nicht schlau zu sein, denn kluger Code ist schrecklich zu lesen und zu pflegen. Schlüsselwort: pflegen!

Meiner Meinung nach sollten Kommentare das Warum und nicht das Was beschreiben. Denken Sie daran, dass in dieser hypothetischen perfekten Welt Ihr Code sauber genug ist, um ein einfaches Lesen zu ermöglichen. Sie müssen nicht erklären, was er tut, sondern warum Sie ihn so oder so gewählt haben.

Wenn Sie ein Versionsverwaltungssystem verwenden, können Sie die Festschreibungsnachricht verwenden, um alle (und sich selbst) darüber zu informieren, was Sie zu einem bestimmten Zeitpunkt getan haben und was noch wichtiger ist, warum

1
Sergio

Ich denke, wir müssen zwischen Dokumentation und Expressivität des Codes unterscheiden.

Beim Debuggen oder Überprüfen von Code lesen Sie kein Buch. Meistens möchten Sie nur von Methode zu Methode springen und schnelle Verbindungen herstellen, um ein grundlegendes Verständnis dafür zu erhalten, was zur Laufzeit vor sich geht. Es ist nicht die Dokumentation um den Code, sondern die Ausdruckskraft der Codesignaturen, die in diesem Prozess wichtig ist, ihre Fähigkeit, aussagekräftig zu sein genug, dass Sie sie sofort identifizieren und Ihrem eigenen internen Aufrufstapel hinzufügen können. An diesem Punkt neigt unser Gehirn (zumindest mein Gehirn funktioniert so;)) dazu, große Kommentarblöcke eher als Rauschen als als Hilfe zu betrachten. Daher sind hier einzeilige Kommentare oder noch besser nur selbstbeschreibende Methoden- und Objektnamen ausreichend.

Wenn Sie das Buch einer bestimmten Klasse oder Funktion "lesen" möchten, sind die Komponententests ein viel besserer Ort dafür. Gut konzipierte Unit-Tests sind von Natur aus aufschlussreich und viel mehr dokumentieren (dh erklärend, detailliert) als die dicksten von Kommentarblöcke, da sie 1/die Erwartungen an genau das enthalten, was dieser Code tun soll, und 2/die Fähigkeit, diese Erwartungen mit dem tatsächlichen Code zu vergleichen. Ein bestehender Test ist hundertmal zuverlässiger als jeder Kommentar in Bezug auf die Dokumentation, da er beweist, dass das, was er behauptet, wahr ist.

1
guillaume31

Einige Codes sind einfach nicht selbst dokumentiert und erfordern einen Kommentar von einem Mitmenschen, der dieses Stück verstanden und getestet hat. Was ich unten habe, reicht einfach nicht aus, um es zu verstehen, denke ich.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}
1
Job

Ich bevorzuge im Allgemeinen das Schreiben von selbstdokumentierendem Code mit unklaren Kommentaren, da ich denke, dass der meiste Code sich selbst nicht vollständig dokumentieren wird.

1
Abbafei

Sie möchten das Schreiben von Kommentaren vermeiden, genauso wie Sie jegliche Dokumentation vermeiden möchten. Wenn es um die Programmiersprache selbst geht, arbeiten alle (fast) mit demselben Wortschatz und derselben Syntax.

Wenn Ihre App für eine bestimmte Domain bestimmt ist, kann es schwierig sein, alle Beteiligten dazu zu bringen, sich auf ein gemeinsames Vokabular zu einigen und/oder es einzurichten. Wir haben gelernt, Abkürzungen und umfangreiche Fachsprache zu vermeiden, aber ich werde es nennen

EBITDA

und nicht

EquityBeforeInterestTaxesDepreciationAndAmortization

Wenn Sie einen nicht kennen, verstehen Sie den anderen wahrscheinlich nicht. Wenn das Unternehmen eine ungewöhnliche Implementierung hat, würde ein Kommentar dem nächsten Programmierer helfen, der möglicherweise Erfahrung in diesem Bereich hat, aber nicht dieser bestimmten Firma (was die Dinge nur komplizierter macht.).

1
JeffO

Kommentare sind ein Muss. Denn wenn Sie Code schreiben, schreiben Sie für Ihre aktuellen Anforderungen, aber auch für die Menschen in der Zukunft, die Ihren Code lesen, herausfinden müssen, was Sie tun und warum und wie Sie Änderungen daran vornehmen können.

Wenn Sie dies nur berücksichtigen, beim Codieren/Programmieren?

Wie kann ich das Verständnis und die Änderung für zukünftige Codierer dieses Codes, an dem ich arbeite, erleichtern? Dann machen Sie einen guten Job. Wenn Sie dies nicht tun, machen Sie es anderen nur schwer, Ihren Code zu ändern, und stellen Sie sich nicht vor, dass dies niemals der Fall sein wird. Das ist selten ...

Bei den meisten meiner Jobs musste ich immer den Code anderer Leute ändern und am schrecklichsten geschrieben, schlecht dokumentiert.

Ihre Gewohnheit, das Codedokument für sich selbst zu halten, besteht also darin, keine Due Diligence durchzuführen.

Als Programmierer müssen wir die Selbstdisziplin üben, die völlig a.r. für unerfahrene Programmierer, die aber Gewohnheiten haben müssen, um all die schrecklichen Erfahrungen zu vermeiden, die wir mit dem Code anderer Leute gemacht haben. Oder schauen Sie sich Monate, Jahre später, unseren eigenen Code an.

Check out http://thedailywtf.com Sie haben jede Menge humorvolle, aber echte Geschichten über Programmierer, die ihre Due Diligence einfach nicht durchgeführt haben.

0
crosenblum

An der Universität wurde uns beigebracht, jede Codezeile in Englisch mit einem Kommentar neu zu formulieren (wahrscheinlich nur, um zu verstehen, was Code tatsächlich tut, anstatt nur etwas zu kopieren/einzufügen und auf das Beste zu hoffen).

Persönlich denke ich, dass Ihr Code verdammt durcheinander kommt und ihn weniger lesbar macht, als wenn es nur Kommentare oder nur Code wären. Ich bin ein C # -Codierer und die einzigen Kommentare, die ich ständig mache, sind die "Triple-Slash" -Kommentarblöcke, die in der IntelliSense-Dokumentation interpretiert werden. Wenn ich mich wegen einer bestimmten Art, etwas zu tun, besonders schuldig fühle oder es besonders kryptisch aussieht, gebe ich eine weitere Erklärung, aber das war es auch schon.

IMO: Selbstdokumentierender Code ist Code, bei dem Variablen- und Methodennamen aussagekräftige und kontextbezogene Namen erhalten, damit sie ihren Zweck beschreiben.

0
James Love

Wenn Sie Ihren Code mehrmals überprüft haben und immer noch keinen Weg gefunden haben, jemandem, der die Domain kennt, die Absicht klar zu machen. Schreiben Sie die Funktion neu. Immerhin sind es nicht mehr als 10-20 Zeilen. Wenn es länger dauert, schreibe die Funktion trotzdem zu lang und das ist ein Teil dessen, warum es nicht lesbar ist :) Spülen-Wiederholen

und im unwahrscheinlichen Fall ist immer noch unklar, was der Code tut, und Sie haben daran gedacht, Ihre Kollegen um Hilfe zu bitten. Na dann, wir alle danken Ihnen, dass Sie bei der Weiterentwicklung von Linux mitgeholfen haben, denn es ist Kernel-Code, den Sie schreiben, oder? wenn nicht spülen-wiederholen von oben :)

Einfach gesagt, schreibe nicht, dass du Kommentare bist. CODE sie

0
Rune FS

Schauen Sie sich Code Complete 2nd Edition an, S. 128-129.

Abstrakte Datentypen bewahren Sie vor diesem Rätsel. Selbstdokumentierender Code ist der richtige Weg. Kommentare können nützlich sein, aber mit

reale Entitäten statt Implementierungen auf niedriger Ebene

sie können die Verwendung von Kommentaren vermeiden.

Eine Sache über Kommentare ist, dass Sie sie einmal schreiben, aber Sie sehen sie nicht, wenn Sie die Funktion implementieren, sondern nur, wenn Sie die Funktion ändern.

Kommentare sind sehr nützlich, wenn sie von IDE wie Delphi 2009+ oder JavaDoc funktionieren) interpretiert werden. Dies ist jedoch eher eine strukturierte Auszeichnungssprache. In gewissem Sinne programmieren Sie also Ihre Dokumentation. Das ist sehr klug.

0
Peter Turner

Ich glaube an das Mantra, dass Code sich nicht selbst dokumentiert, weil Sie der beste Programmierer der Welt sein könnten (Ada) und dennoch nichts darüber verstehen, was vor sich geht, aber wenn Sie warum und in kurzer Zeit dokumentieren Wie Ihr Code das tut, was er tut, Sie werden sich und anderen in Zukunft helfen.

0
Coyote21