Ich habe gesucht, aber nicht gefunden, wonach ich gesucht habe. Bitte verlinken Sie mich, 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. Meiner persönlichen Meinung nach sollte Code beschreibend sein und meist keine Kommentare erfordern, es sei denn, der Code kann sich nicht selbst beschreiben.

Im angegebenen Beispiel

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

Der Autor sagte, dieser Code sollte kommentiert werden, 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-357130

Der Autor antwortete, der Kommentator sei "einer dieser Leute", dh ein schlechter Programmierer.

Was sind alle anderen Ansichten über selbstbeschreibenden Code und kommentierenden Code?

Ich schreibe lieber selbstdokumentierenden Code. Ein Leitfaden dafür ist Clean Code .

Das bedeutet natürlich nicht, dass man niemals Kommentare verwenden sollte - sie haben ihre Rolle, aber IMHO sollten Sie sie vorsichtig 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 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 Code-Teile geschrieben, einfach weil ich seltsame und lustige Namen für alle Code-Entitäten verwendet habe, wie ich es mir vorgestellt habe. Bis mein Lehrer eine meiner Aufgaben zurückwarf und höflich bemerkte, dass er nicht herausfinden konnte, welches Modul das Wichtigste war :-) Das war eine gute Lektion, deshalb bemühte ich mich, mich darauf zu konzentrieren, immer besser lesbaren Code zu schreiben. Heutzutage bekomme ich kaum Beschwerden von Teamkollegen.

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

Keine Menge an Tricks bei der Benennung wird das Warum und Woher enthüllen, daher müssen Sie Kommentare hinzufügen, um den Zweck der verschiedenen Codebits zu erläutern.

Alle anderen Kommentare können sicher entfernt werden.

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

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

Kommentieren Sie also Ihren Code. Natürlich nicht jede Zeile (Himmel, nein), aber setzen Sie ein paar Kommentarzeilen über eine Funktion / ein Unterprogramm / ein Modul oder einen besonders kniffligen Teil und sagen Sie kurz, was es tut. Du wirst dich in ein oder zwei Jahren bedanken.

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

Ich glaube, beide Lager haben sich überschneidende Argumente und stimmen in den meisten Fällen überein, nur die Art und Weise, wie sie erreicht werden, ist etwas anders.

Überlappende Argumente

• Code sollte lesbar sein.
• Kommentare sollten nicht genau dasselbe aussagen wie der Code, sondern bei Bedarf weitere Einblicke geben.
• Alle Variablen- / Funktionsnamen sollten gut durchdacht sein, damit sie eine gute Darstellung dessen geben, was sie sind / tun.
• Doppelter Code sollte verhindert werden.

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

Selbstbeschreibender Code

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

Mehr Kommentare

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

• Einfacher Code führt häufig zu Mehrdeutigkeiten, die dennoch 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 sie zum ersten Mal finden.

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

Um zu demonstrieren, wird Code im 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 um TDD zu vereinfachen). Dies führt zur Funktionshölle . Der Code ist weniger lesbar als ursprünglich, und während der Umgestaltung wurde nicht daran gedacht, wiederverwendbaren Code zu kapseln.

Andererseits sehen Sie oft APIs, in denen jede Funktion kommentiert ist, nur weil "Kommentare gut sind". Die Dinge, die hätten kommentiert werden sollen, sind es immer noch nicht.

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

Ich frage mich, warum er nicht gerne kommentiert: P

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

Sehen Sie sich Lese- und Schreibprogramme als extremen Stil an.

Die kurze, bessere und richtige Antwort

Die Idee, dass gut geschriebener, "selbst dokumentierter Code" alles ist, was Sie brauchen, ist ein Anti-Pattern und sollte sterben, selbst wenn es Ausnahmen für Kommentare gibt, die das "Warum" erklären. Es ist ein Mythos, dass Sie den gesamten Code für jeden Algorithmus immer so klar schreiben können, dass jeder Programmierer einen Blick darauf werfen und ihn abrufen kann. Noch wichtiger ist, dass Programmierer, die glauben , klaren Code zu schreiben, dies häufig nicht tun.

Eine viel bessere Antwort als Kommentare sollte nur verwendet werden, um zu erklären, "warum" Kommentare sollten:

• erkläre "warum" (natürlich)
• Erklären Sie "Was" in einzelnen Zeilen nur, wenn der Code komplex oder der Zweck unklar ist und es sich nicht lohnt, ihn weiter zu vereinfachen
• Erklären Sie "Was" für Codeblöcke, um das Verständnis zu beschleunigen und das zu lokalisieren, was Sie benötigen

Die Erklärung zum Sichern

Die Leute denken fälschlicherweise, dass der einzige Grund, warum sie Kommentare verwenden, darin besteht, zu erklären, was eine Codezeile bedeutet. Die Wahrheit ist, dass das Kommentieren von Code vor allem dazu dient, diesen schneller zu machenDurchsuchen Sie Ihren Code und finden Sie, wonach Sie suchen. Wenn ich später zum Code zurückkehre oder den Code eines anderen lese, kann ich zwar einen Teil des gut geschriebenen Codes lesen und verstehen - aber ist es nicht schneller und einfacher, den Kommentar oben zu lesen, in dem steht, was dieser Teil des Codes bewirkt, und Überspringe es insgesamt, wenn es nicht das ist, wonach ich suche? Warum sitzen Sie da und finden Sie überhaupt den Code heraus, auch wenn er gut geschrieben ist, wenn Sie ein paar Kommentare lesen und eine ganze Funktion verstehen können? Aus diesem Grund verwenden wir beschreibende Namen für Funktionen - niemand sagt, dass ich keinen beschreibenden Namen für meine Funktion verwenden muss, weil jemand einfach durch meinen sauber geschriebenen Code schauen kann, um zu sehen, was er tut.

Wenn ich zum Beispiel die Funktion eines anderen durchschaue, ist es einfacher, den Code zeilenweise durchzugehen, um zu sehen, was er tut, oder auf drei gut geschriebene Kommentare in der Funktion zu blicken, um genau zu sehen, was die Funktion tut und wo es macht es?

Ein weiteres Anti-Pattern ist der übermäßige Gebrauch von Funktionen, um Ihren Code zu kommentieren. Gut benannte Funktionen sind ein wichtiger Bestandteil der Codedokumentation, aber manchmal trennen Programmierer 2-3 Codezeilen, die sonst nirgends verwendet werden, in eine Funktion für Dokumentationszwecke. Warum ist die Überbeanspruchung von Funktionen besser als die Überbeanspruchung von Kommentaren? Das Verwenden solcher Funktionen ist dasselbe wie das Umfassen von GOTO-Anweisungen - es wird Spaghetti-Code erstellt, dem man nur schwer folgen kann.

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

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

Nun, die Sache mit dem selbstdokumentierenden Code ist, dass Sie in dieser Funktion Folgendes finden würden:

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

Das ist selbsterklärend, wenn Sie den Funktionsnamen haben, da er nur aus zwei Zeilen besteht. Wenn die Dinge komplizierter, müssen Sie entweder alle paar Zeilen Code in einer Funktion mit einem beschreibenden Namen wickeln, oder die Nutzung Kommentare erforderlichenfalls .

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

Kommentare und der selbstdokumentierte Bereinigungscode sind unterschiedlich. Code dreht sich alles darum, wie man Dinge macht. Und Kommentare sollten den Warum- Teil abdecken , der unabhängig von Ihrer Sprache nicht im Code erklärt werden kann. Auch wenn Ihre Sprache sehr eingeschränkt ist und Sie keine Verträge, keine statischen Spezifikationen und auch keine Behauptungen haben, sollten Kommentare die Randprobleme Ihres Codes abdecken.

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

$ extension = GetFileExtension ($ image_name);

Kann ich ein Array von Bildnamen an Ihr Beispiel senden oder nimmt es nur ein Bild auf? Unterstützt es irgendwelche Dateitypen oder nur einige von ihnen? Wird es die Saite für mich sichern oder muss ich es tun? Wenn der Dateityp nicht existiert, benachrichtigt er mich?

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

Das eine schließt das andere nicht aus. Auch wenn Ihr Code selbstkommentiert ist, benötigen Sie unter Umständen regelmäßige Kommentare, um zu erklären, warum Ihr selbstkommentierender Code genau das tut, was er tut.

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

Versuche einfach nicht schlau zu sein, denn schlauer Code ist schrecklich zu lesen und zu pflegen. Stichwort: pflegen !

Meiner Meinung nach sollten Kommentare das Warum und nicht das Was beschreiben. Denken Sie in dieser hypothetischen, perfekten Welt daran, dass 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 auf diese oder jene Weise 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

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 Vokabular 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 zu etablieren. Wir werden unterrichtet, 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, hilft ein Kommentar dem nächsten Programmierer, der vielleicht Erfahrung auf diesem Gebiet hat, aber nicht dieser speziellen Firma (was die Sache nur komplizierter macht).

Ich denke, wir müssen zwischen Dokumentation und Ausdruckskraft des Codes unterscheiden.

Beim Debuggen oder Überprüfen von Code lesen Sie kein Buch. Die meiste Zeit möchten Sie nur von Methode zu Methode springen und schnelle Verbindungen in Ihrem Kopf herstellen, um ein grundlegendes Verständnis dafür zu erhalten, was zur Laufzeit vor sich geht. Es ist nicht die Dokumentation rund um den Code, sondern die Expressivität der Codesignaturendie in diesem Prozess wichtig, ihre Fähigkeitaussagekräftig genug zu seindass man sie sofort erkennen kann und fügen Sie sie in Ihren eigenen internen CallStack. Zu diesem Zeitpunkt tendiert unser Gehirn (zumindest meins funktioniert so;)) dazu, große Kommentarblöcke eher als Geräusch als als als Hilfe zu betrachten. Daher sind einzeilige Kommentare oder noch besser nur selbstbeschreibende Methoden- und Objektnamen ausreichend.

Wenn Sie das Buch einer bestimmten Klasse oder Funktion "lesen" möchten, ist dies in den Komponententests viel besser. Gut gestaltete Komponententests sind von Natur aus aufschlussreich und viel dokumentierender (dh erklärender, detaillierter) als die dicksten Kommentarblöcke, da sie 1 / die Erwartungen darüber enthalten, was genau dieser Code tun soll und 2 / die Fähigkeit zu überprüfen diese Erwartungen gegen den realen Code. Ein bestandener Test ist hundertmal zuverlässiger als jeder Kommentar in Bezug auf die Dokumentation, da er beweist, dass das, was er behauptet, wahr ist.

Einige Codes sind einfach nicht selbstdokumentiert und erfordern einen Kommentar von einem Mitmenschen, der das 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;
}

Ich bevorzuge im Allgemeinen das Schreiben von selbstdokumentierendem Code, wobei Kommentare unklar sind, da ich denke, dass sich der meiste Code nicht vollständig selbst dokumentieren lässt.

An der Universität wurde uns beigebracht, so gut wie jede Codezeile in Englisch mit einem Kommentar neu zu formulieren (wahrscheinlich nur, um uns die Gewohnheit zu machen, 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 zum Teufel wird, wenn er erstellt wird weniger macht lesbar ist, als wenn es nur Kommentare oder nur Code wären. Ich bin ein C # -Codierer und die einzigen Kommentare, die ich die ganze Zeit mache, sind die Kommentarblöcke mit drei Schrägstrichen, die zurück in die IntelliSense-Dokumentation interpretiert werden. Wenn ich mich wegen einer bestimmten Art, etwas zu tun, besonders schuldig fühle oder wenn es besonders kryptisch aussieht, gebe ich eine weitere Erklärung, aber das ist es auch.

IMO: Selbstdokumentierender Code ist Code, in dem Variablen- und Methodennamen aussagekräftige und kontextbezogene Namen erhalten, damit sie beschreiben, wozu sie dienen.

Wenn Sie Ihren Code mehrmals überarbeitet haben und immer noch keinen Weg gefunden haben, die Absicht für jemanden klar zu machen, der die Domain kennt. Schreiben Sie die Funktion neu. Immerhin sind es nicht mehr als 10-20 Zeilen. Wenn es länger dauert, wird die Funktion sowieso zu lang und das ist ein Teil des Grundes, warum sie 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 für Ihre Hilfe bei der Weiterentwicklung von Linux, denn es ist der Kernel-Code, den Sie schreiben, oder? wenn nicht spülen-von oben wiederholen :)

Einfach ausgedrückt, schreiben Sie nicht, dass Sie Kommentare sind, CODE sie

Check out Code Complete 2. Ausgabe, 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, Sie sehen sie nur, wenn Sie die Funktion ändern.

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

Ich glaube an das Mantra, dass sich Code 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 geringem Umfang dokumentieren Wie Ihr Code tut, was er tut? Sie werden sich und anderen in Zukunft helfen.

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

Wenn Sie dies bedenken, wenn Sie codieren / programmieren?

Wie kann ich das für zukünftige Codierer dieses Codes, an dem ich arbeite, leichter verständlich machen und modifizieren, dann werden Sie einen guten Job machen. Gelingt dies nicht, 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 ändern und war schrecklich geschrieben und schlecht dokumentiert.

Ihre Angewohnheit, das Codedokument für sich selbst zu halten, besteht also darin, keine Due Diligence zu betreiben.

Als Programmierer müssen wir die Selbstdisziplin üben, die für unerfahrene Programmierer völlig anders zu sein scheint, aber Gewohnheiten haben muss, um all die schrecklichen Erfahrungen zu vermeiden, die wir mit dem Code anderer Leute gemacht haben. Oder Jahre später sogar unseren eigenen Code betrachten.

Unter http://thedailywtf.com finden Sie jede Menge humorvoller, aber echter Geschichten über Programmierer, die ihre Due Diligence-Prüfung einfach nicht durchgeführt haben.