Selbstdokumentierender Code Vs. Kommentierter Code

22

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?

Phill
quelle
1
@ Péter - Ich habe mir das angeschaut, aber ich wollte eher die persönliche Meinung der Leute einholen, anstatt Kommentare als Code-Gerüche zu definieren oder nicht.
Phill
2
Ich finde diesen Artikel ... schrecklich zu lesen. Sehr beleidigend.
Sevenseacat
@ Karpie - Hab ich :(
Phill
3
"Warum Sie ein schlechter PHP-Programmierer sind" Antwort: Weil Sie in PHP programmieren.
Thomas Eding
Ihre bevorzugte Methode besteht im Wesentlichen darin, Funktionsaufrufe zu verwenden, um Ihren Code zu kommentieren. Warum nicht dazu Kommentare verwenden? Funktionen sollten nur für wiederverwendbaren Code verwendet werden. Ich persönlich hasse es, den Code eines anderen auf diese Weise zu befolgen, aus dem gleichen Grund, aus dem die GOTO-Anweisung böse ist - sie erstellt Spaghetti-Code. Dies wird durch moderne IDEs verbessert, aber nicht jede Sprache und jeder Programmierer kann diese IDEs verwenden und sie sind immer noch desorientiert. Ehrlich gesagt stimme ich zu, dass Sie Codeabschnitte kommentieren sollten, die auf einen Blick nicht klar sind - dies macht das Lesen Ihres Codes nur so viel schneller und einfacher.
Dallas

Antworten:

46

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.

Péter Török
quelle
Ich liebe dieses Buch :)
Phill
Ich finde Kommentare immer noch wertvoll, um die verwendete Strategie auszudrücken, und diejenigen, die abgelehnt wurden (mit dem Grund). Ich bin damit einverstanden, dass Mikrokommentare im Allgemeinen nutzlos sind.
Matthieu M.
9
Eines meiner Lieblingszitate aus Clean Code ist, dass jeder Kommentar ein Fehler ist, sich nicht in Code auszudrücken.
Doval
6
@Doval: Eine interessante Philosophie, zumindest im Hinblick auf Kommentare, was Code macht . Auf der anderen Seite können einige der nützlichsten Kommentare die sein, warum Code etwas nicht tut - ein Konzept, von dem ich nicht denke, dass es von Code erwartet werden sollte, dass es es ausdrückt.
Supercat
1
Stimme überhaupt nicht zu. Keine Menge an Namen wird den Zweck der Logik vollständig beschreiben.
Kolob Canyon
65

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.

biziclop
quelle
3
+1 Das Beispiel im verlinkten Artikel besagt: "Machen Sie Kommentare in Situationen, in denen der Zweck des von mir geschriebenen Codes nicht sofort ersichtlich ist." - Es ist nur albern zu glauben, dass Code für sich allein einen Zweck kommunizieren kann , weil Maschinen selbst keinen Zweckbegriff haben. Gegenbeispiel: Wir haben Fehler in fast jeder Software, die jemals geschrieben wurde. Dies ist eine Binsenweisheit. Wenn ein Computer den Zweck (das Warum ) verstehen würde, würde er sich einfach weigern, etwas anderes als das zu tun, was wir beabsichtigt hatten, anstatt pflichtgemäß das nachzuvollziehen, was / wann / wie / wo dies zum Fehler geführt hat.
David Meister
Der gesamte Code in einer Funktion sollte vorhanden sein, um den Zweck der Funktion zu erfüllen, dh was sie tut, z. B. Text in eine Datei schreiben, die Funktion "writeTo (String text, File file)". Wenn ein Code einen anderen Zweck hat, z. B. die Überprüfung der Voraussetzungen, z. B. zu überprüfen, ob die Datei vorhanden ist, UND dies nicht offensichtlich ist, ist es möglicherweise besser, als einen Kommentar eine neue Funktion zu schreiben, z. B. "checkWritable (File file)". Codequalität ist keine dogmatische Checkliste, aber wenn es Kommentare braucht , ist das ein schlechtes Zeichen, und das "Warum" ist kein guter Grund, sie zu brauchen . Warum hat das Huhn die Straße überquert?
Trylks
2
@Trylks Das funktioniert in einigen Fällen, aber nicht für alle. Stellen Sie sich folgendes Szenario vor : for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Nun, dies ist weder etwas, was sich aus dem Zweck der einschließenden Funktion ergibt, noch könnte es in seine eigene Funktion zerlegt werden. Wenn Sie es unkommentiert lassen, ist das eindeutig schlecht. Sie fügen also einen Kommentar hinzu, um Ihre Absicht zu verdeutlichen.
Biziclop
2
@Trylks Außerdem, auch wenn wir Ihr Beispiel nehmen, zerlegen Sie Ihren Check-out in eine Methode und nennen sie großartig. Jetzt müssen Sie nur noch erklären, warum Sie überprüfen müssen, ob die Datei beschreibbar ist. :)
biziclop
38

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.

Turm
quelle
Kenne ich schon. "Weniger lesbarer Code" sollte in gut lesbaren Code umgewandelt werden. Sprachkenntnisse zählen nicht wirklich: Wenn Sie mit der Syntax nicht vertraut sind, sollten Sie sie zuerst lernen - ehrlich gesagt, das ist die Basis, um professionell zu sein. Der Versuch, schrecklichen Code durch Hinzufügen von Kommentaren auszugleichen, ist keine gute Idee. Kommentare sollten niemals versuchen zu beschreiben, was der Code tut. Ein (allgemeiner) Kommentar ist nur dann gerechtfertigt, wenn Sie das Warum und nicht das Was angeben müssen . Alles andere ist nur Lärm und unnötige zusätzliche Dinge zu pflegen.
Powerslave
PS, ich weiß, dass ich ein bisschen 'zombied' bin :) Entschuldigung
Powerslave
Um Verwirrung zu vermeiden, spreche ich von dem üblichen Fall, in dem Sie nicht durch die geschäftlichen Anforderungen zum Schreiben von fehlerhaftem Code gezwungen werden (z. B. außergewöhnliche Leistung oder Einbau in einen begrenzten Speicher). In anderen (seltenen) Fällen haben Sie keine andere Wahl, als Kommentare zu hinterlassen, was die Belastung des nächsten Opfers etwas erleichtert.
Powerslave
19

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.

Steven Jeuris
quelle
1
@Steven - "Andererseits sieht man 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." Ugh, so frustrierend wahr!
dss539
Das ist eine sehr gute Antwort! Eine Sache, wenn Sie nichts dagegen haben, zur Lesbarkeit von Kommentaren: Ich persönlich glaube nicht, dass Kommentare besser lesbar sind. Wir als Entwickler denken normalerweise im Quellcode, besonders wenn wir uns im "Codierungsmodus" befinden. In diesen Momenten ist die Unbestimmtheit der menschlichen Sprache eher eine Ablenkung als eine Hilfe.
Powerslave
5

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

Vegai
quelle
Ja. Ich meine, wenn Donald Knuth meint, Sie brauchen nicht nur Kommentare, sondern manchmal auch Kapitel davon, würde ich mindestens zweimal darüber nachdenken, bevor Sie nicht einverstanden sind.
PeterAllenWebb
3

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.

U / min
quelle
Ich hasse es, wenn Leute ablehnen und nicht einmal einen Kommentar hinterlassen, warum. Hast du den ganzen Beitrag überhaupt gelesen? Was ist da drin nicht einfach und wahr? Womit sind Sie nicht einverstanden? Ich habe das Gefühl, dass die Leute so fest in ihre Idee oder in das, was sie lesen, verstrickt sind, dass sie nicht einmal darüber nachdenken und sofort etwas ablehnen, was ihre Meinung nicht teilt.
3.
3
Ich nehme an, Sie lehnen ein Antimuster ab und nennen es als etwas, das allgemein als richtig anerkannt ist. Ich denke schon, du gehst zu weit. Meistens kann ich mir nicht vorstellen, den Kommentaren so zu vertrauen, wie es scheint. Wenn Sie die Kommentare und nicht den Code blind lesen, sind die Kommentare möglicherweise falsch und veraltet, und Sie werden es nie erfahren. Das ist die Basis für die Verwendung von Funktionen als Dokumentation. Ich bin damit einverstanden, dass Sie nicht zu viele Funktionen an einem Ort haben sollten, obwohl die Lösung definitiv nicht darin besteht, sie durch Kommentare zu ersetzen.
Magus
@ Magus Danke für den Kommentar. Ich gehe davon aus, dass Sie sich auf meine Ausführungen zur Verwendung von Funktionen als Dokumentation bezogen haben. Als ich das noch einmal las, war es meiner Meinung nach schlecht formuliert, so zu klingen, als ob ich beabsichtigte, Funktionen für diesen Zweck überhaupt zu verwenden (im Gegensatz zu der Überbeanspruchung von Funktionen für diesen Zweck). Ich habe diesen Absatz aufgeräumt, um meine ursprüngliche Absicht zu verdeutlichen. Wenn ein Kommentar veraltet ist, ist dies normalerweise ein Zeichen dafür, dass Sie einen Codeabschnitt zu eng kommentiert haben - dass Sie eher die Implementierung als die Absicht kommentiert haben.
Dallas
but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forEs heißt "der Name der Methode / Funktion". Wenn Sie einen Codeblock haben, der keinen Namen hat, aber so lang ist, dass Sie ihn nicht mit einem kurzen Blick erfassen können, liegt möglicherweise das Problem darin.
Biziclop
1
@biziclop Überstunden Ich bin zu dem Schluss gekommen, dass dieses Argument größtenteils semantisch ist, und in der Praxis würde unser Code ähnlich aussehen. Unter der Annahme, dass der Codeblock nicht an mehr als einer Stelle verwendet wird, sehe ich keinen Unterschied zwischen einem Codeblock mit einem kurzen beschreibenden Kommentar oben und einem Codeblock mit einem kurzen beschreibenden Funktionsnamen am oben. Sie sind die gleichen, außer man hat keine Leerzeichen. Sie können beide falsch und veraltet sein. Der einzige Unterschied, den ich wirklich sehe, ist, dass der Code mit einem Kommentar leichter zu lesen ist, da Sie dem Funktionsaufruf nicht an eine separate Stelle folgen müssen.
Dallas
2

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.

user6791
quelle
1
Kannst du ein Beispiel geben. Ich meine das Beispiel in meiner ursprünglichen Frage gegeben. "GetFileExtension" Was ist der Punkt im Kommentar "Ruft die Dateierweiterung einer bestimmten Datei ab"? Die Methode hat bereits beschrieben, was in den Kommentar gehen soll. Wenn die Methode den Namen "GetExtension" trägt, hilft ein Kommentar bei der Klärung, was die Methode tun soll, da die Methode sich nicht selbst erklärt.
Phill
+1 Dies ist eine Frage, bei der Sie Ihre Zielgruppe kennen. Wer wird diese Funktion voraussichtlich nutzen? Wie kannst du ihnen helfen? Was wird deine Hilfe wert sein? Lohnt es sich mehr als ein bisschen Zeit zu investieren, um einen Kommentar hinzuzufügen? Etc. Etc. Etc.
PeterAllenWebb
2
@ PeterAllenWebb: Kein Punkt zu diesem Kommentar überhaupt. Das bedeutet nicht, dass die Funktion nicht kommentiert werden sollte. es sollte. Enthält "Erweiterung" den Punkt oder nicht? Wofür ist der Rückgabewert "foo"? ( null? ""?) Für "foo."? Wird die Übergabe nulleine Ausnahme auslösen oder wird die Funktion (vielleicht null) etwas zurückgeben ?
TJ Crowder
2

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.

Joris Meys
quelle
Ja. Ich denke, man muss "trainiert" sein, um zu denken, dass es das eine oder andere und nicht beides sein sollte.
PeterAllenWebb
2

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.

SK-Logik
quelle
Angenommen, es gibt einen Grund für alles, sollte es kommentiert werden?
JeffO
Ja genau. Aus diesem Grund glaube ich, dass der beste Weg, Ihren Code zu kommentieren, eine geschulte Programmierung ist.
SK-logic
1

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.

Niphra
quelle
5
Sie dehnen das eine viel. Die Funktion erhält die Dateinamenerweiterung. Nicht mehr, nicht weniger. Der Name gibt an, ob ein Array verwendet wird oder nicht (eindeutig nicht). Ich kann mir keine Methode vorstellen, die sich auf den Dateityp stützt, um die Erweiterung zu erhalten. Das Sichern der Zeichenfolge ist die einzige, die möglicherweise enthalten ist, aber ich würde sie niemals erwarten, da jeder PHP-Entwickler weiß: Alle Benutzereingaben sind verdächtig. Sichern Sie sie daher, bevor Sie sie verwenden.
Matt Ellen
2
@Matt: Das "eindeutig nicht" ist ein Hinweis darauf, dass Sie die Wartung nicht sehr oft durchführen. Explizit zu sein, erspart später viel Kopfzerbrechen (und RTFSource) und dokumentiert auch, was der ursprüngliche Autor von ihm erwartet hatte. Ob das in einem Kommentar oder in einem langen Funktionsnamen steht, ist bei weitem nicht so wichtig.
Donal Fellows
Vielleicht war das Beispiel in dieser Frage schlecht, ich habe PHP seit ungefähr 7 Jahren nicht mehr angesprochen, habe C # und ein bisschen Java gemacht, also bin ich es gewohnt, eine IDE zu haben, die mir sagt, welcher Typ zurückgegeben wurde oder Deklaration der Typen.
Phill
1
@Donal Fellows: Hier steht file, singular. Was ist daran zweideutig? Es ist völlig explizit.
Matt Ellen
4
Die Tatsache, dass es jetzt 7 Antworten von 4 Personen gibt, die die Offensichtlichkeit oder das Gegenteil eines einzelnen Funktionsaufrufs diskutieren, legt nahe, dass Sie Kommentare verwenden müssen . Es wird auch die Tatsache hervorgehoben, dass genaue Benennung eine Kunstform für sich ist.
Ant
1

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.

gablin
quelle
Ich denke, dies fällt in meine Meinung, die lautete "Code sollte beschreibend sein und erfordert meist keine Kommentare, es sei denn, der Code kann nicht selbstbeschreibend sein". Wenn Sie Code schreiben, der während des Schreibens gut ist und die Intensität des Codes nicht vollständig erklärt, helfen die Kommentare dabei, den Code aussagekräftiger zu gestalten.
Phill
Code kann niemals seinen Zweck erklären. Wenn Sie einen Hammer sehen, können Sie nicht herausfinden, wofür er ist - ist es, um Schädel zu zertrümmern oder nur um ein rohes Eisen zu schmieden.
SK-logic
1
@ SK-logic:public <T> void hit(T item);
Michael K
@ Michael - genau. Wie wird der Benutzer herausfinden, welche Kategorien von Objekten gehämmert werden können und sollen? Selbst bei einem viel besseren Typsystem ist nicht immer klar, welche Einsatzmöglichkeiten ein Entwickler tatsächlich plant.
SK-logic,
1

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

Sergio
quelle
1

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

JeffO
quelle
1

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.

guillaume31
quelle
1

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;
}
Job
quelle
1

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.

Abbafei
quelle
0

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.

James Love
quelle
0

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

Rune FS
quelle
0

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.

Peter Turner
quelle
0

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.

Coyote21
quelle
0

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.

Crosenblum
quelle