Was stimmt nicht mit Kommentaren, die komplexen Code erklären?

Viele Leute behaupten, "Kommentare sollten erklären, warum, aber nicht wie". Andere sagen, "Code sollte sich selbst dokumentieren" und Kommentare sollten knapp sein. Robert C. Martin behauptet, dass (in meinen eigenen Worten umformuliert) Kommentare häufig "Entschuldigungen für schlecht geschriebenen Code" sind.

Meine Frage lautet wie folgt:

Was ist falsch daran, einen komplexen Algorithmus oder ein langes und verschlungenes Stück Code mit einem beschreibenden Kommentar zu erklären?

Auf diese Weise müssen andere Entwickler (einschließlich Sie selbst) nicht den gesamten Algorithmus Zeile für Zeile lesen, um herauszufinden, was er tut, sondern können einfach den benutzerfreundlichen beschreibenden Kommentar lesen, den Sie im Klartext geschrieben haben.

Englisch ist so konzipiert, dass es von Menschen leicht verstanden werden kann. Java, Ruby oder Perl wurden jedoch entwickelt, um die Lesbarkeit von Menschen und die Lesbarkeit von Computern in Einklang zu bringen und so die Lesbarkeit des Textes zu beeinträchtigen. Ein Mensch kann ein Stück Englisch viel schneller verstehen als ein Stück Code mit der gleichen Bedeutung (solange die Operation nicht trivial ist).

Fügen Sie nach dem Schreiben eines komplexen Codeteils in einer teilweise für Menschen lesbaren Programmiersprache einen beschreibenden und präzisen Kommentar hinzu, der die Funktionsweise des Codes in freundlichem und verständlichem Englisch erklärt.

Einige werden sagen "Code sollte nicht schwer zu verstehen sein", "Funktionen klein machen", "beschreibende Namen verwenden", "Spaghetti-Code nicht schreiben".

Aber wir alle wissen, dass das nicht ausreicht. Dies sind nur Richtlinien - wichtige und nützliche -, aber sie ändern nichts an der Tatsache, dass einige Algorithmen komplex sind. Und sind deshalb schwer zu verstehen, wenn man sie Zeile für Zeile liest.

Ist es wirklich so schlecht, einen komplexen Algorithmus mit ein paar Zeilen Kommentaren zur allgemeinen Funktionsweise zu erklären? Was ist falsch daran, komplizierten Code mit einem Kommentar zu erklären?

In den Begriffen des Laien:

• Es ist nichts Falsches an den Kommentaren an sich. Was falsch ist, ist das Schreiben von Code, der diese Art von Kommentaren benötigt, oder die Annahme, dass es in Ordnung ist, verschachtelten Code zu schreiben, solange Sie ihn im Klartext erklären.
• Kommentare werden nicht automatisch aktualisiert, wenn Sie den Code ändern. Das ist der Grund, warum Kommentare häufig nicht mit dem Code synchronisiert sind.
• Kommentare erleichtern das Testen von Code nicht.
• Entschuldigung ist nicht schlecht. Was Sie getan haben, für das Sie sich entschuldigen müssen (das Schreiben von Code, der nicht leicht zu verstehen ist), ist schlecht.
• Ein Programmierer, der in der Lage ist, einfachen Code zu schreiben, um ein komplexes Problem zu lösen, ist besser als einer, der komplexen Code schreibt und dann einen langen Kommentar schreibt, der erklärt, was sein Code tut.

Endeffekt:

Sich selbst zu erklären ist gut, es ist besser, es nicht zu brauchen.

Es gibt verschiedene Gründe, warum Code kompliziert oder verwirrend ist. Die häufigsten Gründe lassen sich am besten beheben, indem Sie den Code überarbeiten, um ihn weniger verwirrend zu machen, und keine Kommentare hinzufügen.

Es gibt jedoch Fälle, in denen ein ausgewählter Kommentar die beste Wahl ist.

• Wenn es der Algorithmus selbst ist, der kompliziert und verwirrend ist, und nicht nur seine Implementierung - die Art, die in mathematischen Fachzeitschriften geschrieben wird und immer als Mbogos Algorithmus bezeichnet wird -, dann setzen Sie einen Kommentar ganz am Anfang der Implementierung so etwas wie "Dies ist Mbogos Algorithmus zum Auffrischen von Widgets, der ursprünglich hier beschrieben wurde: [URL of Paper]. Diese Implementierung enthält Verfeinerungen von Alice und Carol [URL eines anderen Papiers]." Versuchen Sie nicht, detaillierter darauf einzugehen. Wenn jemand mehr Details benötigt, muss er wahrscheinlich die gesamte Zeitung lesen.

• Wenn Sie etwas, das als eine oder zwei Zeilen in einer speziellen Notation geschrieben werden kann, zu einem großen Globus imperativen Codes erweitert haben, ist es eine gute Möglichkeit, diese eine oder zwei Zeilen in einen Kommentar über der Funktion einzufügen sagen dem Leser , was es soll tun. Dies ist eine Ausnahme vom Argument "Aber was ist, wenn der Kommentar nicht mehr mit dem Code synchron ist?", Da die spezialisierte Notation wahrscheinlich viel einfacher zu finden ist als der Code. (Wenn Sie eine Spezifikation stattdessen in Englisch verfasst haben, ist dies umgekehrt.) Ein gutes Beispiel ist hier: https://dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSScanner.cpp#1057 ...

  /**
   * Scan a unicode-range token.  These match the regular expression
   *
   *     u\+[0-9a-f?]{1,6}(-[0-9a-f]{1,6})?
   *
   * However, some such tokens are "invalid".  There are three valid forms:
   *
   *     u+[0-9a-f]{x}              1 <= x <= 6
   *     u+[0-9a-f]{x}\?{y}         1 <= x+y <= 6
   *     u+[0-9a-f]{x}-[0-9a-f]{y}  1 <= x <= 6, 1 <= y <= 6
  

• Wenn der Code insgesamt unkompliziert ist, aber ein oder zwei Dinge enthält, die übermäßig verwickelt, unnötig oder einfach falsch aussehen , aber aus Gründen so sein müssen, setzen Sie einen Kommentar direkt über das verdächtig aussehende Bit, in das Sie geben die Gründe an . Hier ist ein einfaches Beispiel, in dem nur erklärt werden muss, warum eine Konstante einen bestimmten Wert hat.

  /* s1*s2 <= SIZE_MAX if s1 < K and s2 < K, where K = sqrt(SIZE_MAX+1) */
  const size_t MUL_NO_OVERFLOW = ((size_t)1) << (sizeof(size_t) * 4);
  if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
      nmemb > 0 && SIZE_MAX / nmemb < size)
    abort();
  

Was ist also falsch daran, komplizierten Code mit einem Kommentar zu erklären?

Es geht nicht um richtig oder falsch, sondern um die "Best Practice", wie im Wikipedia-Artikel definiert :

Eine Best Practice ist eine Methode oder Technik, die durchweg bessere Ergebnisse erzielt als mit anderen Mitteln und die als Benchmark verwendet wird.

Die beste Vorgehensweise besteht darin, zuerst den Code zu verbessern und Englisch zu verwenden, wenn dies nicht möglich ist.

Es ist kein Gesetz, aber es ist weitaus üblicher, kommentierten Code zu finden, der umgestaltet werden muss, als umgestalteten Code, der Kommentare erfordert.

Es wird ein Tag kommen, an dem Ihr schöner, perfekt gestalteter, gut strukturierter und lesbarer Code nicht mehr funktioniert. Oder es wird nicht gut genug funktionieren. Oder es entsteht ein Sonderfall, in dem es nicht funktioniert und angepasst werden muss.

An diesem Punkt müssen Sie etwas tun, das die Dinge ändert, damit es richtig funktioniert. Insbesondere bei Leistungsproblemen, aber auch häufig in Szenarien, in denen sich eine der von Ihnen verwendeten Bibliotheken, APIs, Webdienste, Gems oder Betriebssysteme nicht wie erwartet verhält, können Sie Vorschläge machen, bei denen dies nicht der Fall ist notwendigerweise unelegant, aber kontraintuitiv oder nicht offensichtlich.

Wenn Sie keine Kommentare haben, um zu erklären, warum Sie diesen Ansatz gewählt haben, besteht eine sehr gute Chance, dass sich in Zukunft jemand (und möglicherweise sogar Sie) den Code ansieht und prüft, wie er "behoben" werden kann Etwas lesbareres und eleganteres, das versehentlich Ihre Korrektur rückgängig macht, weil es nicht wie eine Korrektur aussieht.

Wenn jeder immer perfekten Code geschrieben hätte, wäre es offensichtlich, dass Code, der unvollständig aussieht, um eine knifflige Intervention aus der realen Welt herumarbeitet, aber so funktionieren die Dinge nicht. Die meisten Programmierer schreiben oft verwirrenden oder etwas verworrenen Code. Wenn wir dem begegnen, ist es eine natürliche Neigung, ihn aufzuräumen. Ich schwöre, meine Vergangenheit ist ein wirklicher Idiot, wenn ich alten Code lese, den ich geschrieben habe.

Daher sehe ich Kommentare nicht als Entschuldigung für schlechten Code, sondern als Erklärung dafür, warum Sie das Offensichtliche nicht getan haben. Mit // The standard approach doesn't work against the 64 bit version of the Frobosticate Librarykönnen zukünftige Entwickler, einschließlich Ihres zukünftigen Selbst, auf diesen Teil des Codes achten und ihn mit dieser Bibliothek testen. Sicher, Sie können die Kommentare auch in Ihre Versionskontroll-Commits einfügen, aber die Leute werden sich diese erst ansehen, nachdem etwas schief gelaufen ist. Sie lesen Codekommentare, wenn sie den Code ändern.

Leute, die uns sagen, dass wir immer theoretisch perfekten Code schreiben sollten, sind nicht immer Leute mit viel Erfahrung im Programmieren in realen Umgebungen. Manchmal müssen Sie Code schreiben, der eine bestimmte Leistung erbringt, manchmal müssen Sie mit fehlerhaften Systemen zusammenarbeiten. Das bedeutet nicht, dass Sie dies nicht auf elegante und gut geschriebene Weise tun können, aber nicht offensichtliche Lösungen bedürfen einer Erklärung.

Wenn ich Code für Hobbyprojekte schreibe, von denen ich weiß, dass niemand sie jemals lesen wird, kommentiere ich immer noch Teile, die ich verwirrend finde - zum Beispiel beinhaltet jede 3D-Geometrie Mathematik, mit der ich nicht ganz zuhause bin -, weil ich weiß, wann ich zurückkomme In sechs Monaten werde ich völlig vergessen haben, wie man dieses Zeug macht. Das ist keine Entschuldigung für schlechten Code, sondern eine Anerkennung einer persönlichen Einschränkung. Alles, was ich tun würde, wenn ich es unkommentiert lassen würde, wäre, mir in Zukunft mehr Arbeit zu schaffen. Ich möchte nicht, dass mein zukünftiges Ich etwas unnötig neu lernen muss, wenn ich es jetzt vermeiden kann. Welchen möglichen Wert hätte das?

Die Notwendigkeit von Kommentaren ist umgekehrt proportional zur Abstraktionsebene des Codes.

Zum Beispiel ist Assemblersprache für die meisten praktischen Zwecke ohne Kommentare unverständlich. Hier ist ein Auszug aus einem kleinen Programm, das Terme der Fibonacci-Reihe berechnet und ausgibt :

main:   
; initializes the two numbers and the counter.  Note that this assumes
; that the counter and num1 and num2 areas are contiguous!
;
    mov ax,'00'                     ; initialize to all ASCII zeroes
    mov di,counter                  ; including the counter
    mov cx,digits+cntDigits/2       ; two bytes at a time
    cld                             ; initialize from low to high memory
    rep stosw                       ; write the data
    inc ax                          ; make sure ASCII zero is in al
    mov [num1 + digits - 1],al      ; last digit is one
    mov [num2 + digits - 1],al      ; 
    mov [counter + cntDigits - 1],al

    jmp .bottom         ; done with initialization, so begin

.top
    ; add num1 to num2
    mov di,num1+digits-1
    mov si,num2+digits-1
    mov cx,digits       ; 
    call    AddNumbers  ; num2 += num1
    mov bp,num2         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jz  .done           ;

    ; add num2 to num1
    mov di,num2+digits-1
    mov si,num1+digits-1
    mov cx,digits       ;
    call    AddNumbers  ; num1 += num2
.bottom
    mov bp,num1         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jnz .top            ;
.done
    call    CRLF        ; finish off with CRLF
    mov ax,4c00h        ; terminate
    int 21h             ;

Selbst mit Kommentaren kann es ziemlich kompliziert sein, zu grocken.

Modernes Beispiel: Regexe sind oft sehr niedrige Abstraktionskonstrukte (Kleinbuchstaben, Nummer 0, 1, 2, neue Zeilen usw.). Sie benötigen wahrscheinlich Kommentare in Form von Mustern (Bob Martin, IIRC, erkennt dies an). Hier ist ein regulärer Ausdruck, der (meiner Meinung nach) mit HTTP- (S) und FTP-URLs übereinstimmen sollte:

^(((ht|f)tp(s?))\://)?(www.|[a-zA-Z].)[a-zA-Z0-9\-\.]+\.(com|edu|gov|m
+il|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(/($|[a-zA-Z0-9\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$

Während die Sprachen die Abstraktionshierarchie verbessern, kann der Programmierer evokative Abstraktionen (Variablennamen, Funktionsnamen, Klassennamen, Modulnamen, Schnittstellen, Rückrufe usw.) verwenden, um eine integrierte Dokumentation bereitzustellen. Es ist faul, dies zu vernachlässigen und Kommentare zu verwenden, um darüber zu schreiben, ein schlechter Dienst für den Betreuer und respektlos gegenüber ihm.

Ich denke dabei an Numerical Recipes in C übersetzt meist wörtlich zu Numerical Recipes in C ++ , die ich schließen , begann als Numerical Recipes (in FORTAN), mit allen Variablen a, aa, b, c, cc, usw. durch jede Version beibehalten. Die Algorithmen mögen korrekt gewesen sein, aber sie haben die Abstraktionen der bereitgestellten Sprachen nicht ausgenutzt. Und sie machen mich fertig. Auszug aus einem Artikel von Dr. Dobbs - Fast Fourier Transform :

void four1(double* data, unsigned long nn)
{
    unsigned long n, mmax, m, j, istep, i;
    double wtemp, wr, wpr, wpi, wi, theta;
    double tempr, tempi;

    // reverse-binary reindexing
    n = nn<<1;
    j=1;
    for (i=1; i<n; i+=2) {
        if (j>i) {
            swap(data[j-1], data[i-1]);
            swap(data[j], data[i]);
        }
        m = nn;
        while (m>=2 && j>m) {
            j -= m;
            m >>= 1;
        }
        j += m;
    };

    // here begins the Danielson-Lanczos section
    mmax=2;
    while (n>mmax) {
        istep = mmax<<1;
        theta = -(2*M_PI/mmax);
        wtemp = sin(0.5*theta);
        wpr = -2.0*wtemp*wtemp;
        wpi = sin(theta);
        wr = 1.0;
        wi = 0.0;
        for (m=1; m < mmax; m += 2) {
            for (i=m; i <= n; i += istep) {
                j=i+mmax;
                tempr = wr*data[j-1] - wi*data[j];
                tempi = wr * data[j] + wi*data[j-1];

                data[j-1] = data[i-1] - tempr;
                data[j] = data[i] - tempi;
                data[i-1] += tempr;
                data[i] += tempi;
            }
            wtemp=wr;
            wr += wr*wpr - wi*wpi;
            wi += wi*wpr + wtemp*wpi;
        }
        mmax=istep;
    }
}

Als Sonderfall zur Abstraktion verfügt jede Sprache über Redewendungen / kanonische Codefragmente für bestimmte allgemeine Aufgaben (Löschen einer dynamischen verknüpften Liste in C). Unabhängig davon, wie sie aussehen, sollten sie nicht dokumentiert werden. Programmierer sollten diese Redewendungen lernen, da sie inoffiziell Teil der Sprache sind.

Also das Mitnehmen: Nicht-idiomatischer Code, der aus einfachen Bausteinen besteht, die nicht vermieden werden können, benötigt Kommentare. Und das ist WAAAAY weniger notwendig, als es passiert.

Ich glaube nicht, dass an Kommentaren im Code etwas falsch ist. Die Idee, dass Kommentare meiner Meinung nach irgendwie schlecht sind , ist darauf zurückzuführen, dass einige Programmierer die Dinge zu weit gehen. Es gibt in dieser Branche eine Menge Bandwagoning, insbesondere in Richtung extremer Ansichten. Irgendwo auf dem Weg wurde kommentierter Code zu schlechtem Code und ich bin mir nicht sicher warum.

Kommentare haben Probleme - Sie müssen sie auf dem neuesten Stand halten, wenn Sie den Code aktualisieren, auf den sie verweisen, was viel zu selten vorkommt. Ein Wiki oder ähnliches ist eine geeignetere Ressource für eine gründliche Dokumentation Ihres Codes. Ihr Code sollte lesbar sein, ohne dass Kommentare erforderlich sind. In Versionskontroll- oder Revisionsnotizen sollten Sie die von Ihnen vorgenommenen Codeänderungen beschreiben.

Keiner der oben genannten Punkte macht jedoch die Verwendung von Kommentaren ungültig. Wir leben nicht in einer idealen Welt. Wenn eine der oben genannten Situationen aus irgendeinem Grund fehlschlägt, hätte ich lieber einige Kommentare , auf die ich zurückgreifen könnte.

Ich denke, du liest ein bisschen zu viel in dem, was er sagt. Ihre Beschwerde besteht aus zwei Teilen:

Was ist falsch daran, (1) einen komplexen Algorithmus oder (2) ein langes und verschlungenes Stück Code mit einem beschreibenden Kommentar zu erklären?

(1) ist unvermeidlich. Ich glaube nicht, dass Martin dir widersprechen würde. Wenn Sie so etwas wie die schnelle Quadratwurzel schreiben , brauchen Sie einige Kommentare, auch wenn es sich nur um "böses Fließkomma-Bit-Level-Hacking" handelt. Abgesehen von etwas Einfachem wie einer DFS- oder Binärsuche ist es unwahrscheinlich, dass die Person, die Ihren Code liest, Erfahrung mit diesem Algorithmus hat. Daher sollte in den Kommentaren zumindest erwähnt werden, was es ist.

Der meiste Code ist jedoch nicht (1). In den seltensten Fällen werden Sie eine Software schreiben, die nichts anderes als handgerollte Mutex-Implementierungen, obskure lineare Algebraoperationen mit unzureichender Bibliotheksunterstützung und neuartige Algorithmen ist, die nur der Forschungsgruppe Ihres Unternehmens bekannt sind. Der meiste Code besteht aus Bibliotheks- / Framework- / API-Aufrufen, E / A, Boilerplate und Komponententests.

Über diese Art von Code spricht Martin. Und er beantwortet Ihre Frage mit dem Zitat von Kernighan und Plaugher am Anfang des Kapitels:

Kommentieren Sie keinen schlechten Code - schreiben Sie ihn neu.

Wenn Sie lange, verschlungene Abschnitte in Ihrem Code haben, ist es Ihnen nicht gelungen, Ihren Code sauber zu halten . Die beste Lösung für dieses Problem ist nicht, einen absatzlangen Kommentar oben in die Datei zu schreiben, um zukünftigen Entwicklern zu helfen, sich darin zurechtzufinden. Die beste Lösung ist, es neu zu schreiben.

Und genau das sagt Martin:

Die ordnungsgemäße Verwendung von Kommentaren dient dazu, unser Versagen, sich im Code auszudrücken, auszugleichen. Kommentare sind immer Fehler. Wir müssen sie haben, weil wir nicht immer herausfinden können, wie wir uns ohne sie ausdrücken können, aber ihr Gebrauch ist kein Grund zum Feiern.

Das ist dein (2). Martin stimmt zu, dass langer, verschachtelter Code Kommentare benötigt - aber er gibt dem Programmierer, der ihn geschrieben hat, die Schuld für diesen Code, nicht irgendeine nebulöse Vorstellung, dass "wir alle wissen, dass das nicht genug ist". Er argumentiert, dass:

Klarer und aussagekräftiger Code mit wenigen Kommentaren ist unübersichtlichem und komplexem Code mit vielen Kommentaren weit überlegen. Anstatt deine Zeit damit zu verbringen, die Kommentare zu schreiben, die das Chaos erklären, das du angerichtet hast, solltest du es damit verbringen, dieses Chaos zu beseitigen.

Was ist falsch daran, einen komplexen Algorithmus oder ein langes und verschlungenes Stück Code mit einem beschreibenden Kommentar zu erklären?

Nichts als solches. Das Dokumentieren Ihrer Arbeit ist eine gute Praxis.

Das heißt, Sie haben hier eine falsche Dichotomie: Schreiben von sauberem Code vs. Schreiben von dokumentiertem Code - die beiden sind nicht gegensätzlich.

Sie sollten sich darauf konzentrieren, komplexen Code zu vereinfachen und in einfacheren Code zu abstrahieren, anstatt zu denken, "komplexer Code ist in Ordnung, solange er kommentiert ist".

Im Idealfall sollte Ihr Code einfach und dokumentiert sein.

Auf diese Weise müssen andere Entwickler (einschließlich Sie selbst) nicht den gesamten Algorithmus Zeile für Zeile lesen, um herauszufinden, was er tut, sondern können einfach den benutzerfreundlichen beschreibenden Kommentar lesen, den Sie im Klartext geschrieben haben.

Wahr. Aus diesem Grund sollten alle Ihre öffentlichen API-Algorithmen in der Dokumentation erläutert werden.

Fügen Sie nach dem Schreiben eines komplexen Codeteils in einer teilweise für Menschen lesbaren Programmiersprache einen beschreibenden und präzisen Kommentar hinzu, der die Funktionsweise des Codes in freundlichem und verständlichem Englisch erklärt.

Idealerweise sollten Sie nach dem Schreiben eines komplexen Code Folgendes tun (keine vollständige Liste):

• halte es für einen Entwurf (dh plane es neu zu schreiben)
• Formalisieren Sie die Algorithmus-Einstiegspunkte / Schnittstellen / Rollen / usw. (analysieren und optimieren Sie die Schnittstelle, formalisieren Sie Abstraktionen, dokumentieren Sie Vorbedingungen, Nachbedingungen und Nebenwirkungen und dokumentieren Sie Fehlerfälle).
• schreiben Sie Tests
• Aufräumen und Refactor

Keiner dieser Schritte ist trivial (dh jeder kann einige Stunden dauern) und die Belohnungen dafür sind nicht unmittelbar. Daher werden diese Schritte (fast) immer beeinträchtigt (von Entwicklern, Managern, Terminen, Markteinschränkungen / anderen realen Bedingungen, mangelnder Erfahrung usw.).

[...] einige Algorithmen sind komplex. Und sind deshalb schwer zu verstehen, wenn man sie Zeile für Zeile liest.

Sie sollten sich niemals darauf verlassen müssen, die Implementierung zu lesen, um herauszufinden, was eine API tut. Wenn Sie dies tun, implementieren Sie Client-Code basierend auf der Implementierung (anstelle der Schnittstelle) und das bedeutet, dass Ihre Modulkopplung bereits zum Teufel ist. Sie führen möglicherweise undokumentierte Abhängigkeiten mit jeder neuen Codezeile ein, die Sie schreiben, und sind fügte bereits technische Schulden hinzu.

Ist es wirklich so schlecht, einen komplexen Algorithmus mit ein paar Zeilen Kommentaren zur allgemeinen Funktionsweise zu erklären?

Nein, das ist gut. Es reicht jedoch nicht aus, ein paar Kommentarzeilen hinzuzufügen.

Was ist falsch daran, komplizierten Code mit einem Kommentar zu erklären?

Die Tatsache, dass Sie keinen komplizierten Code haben sollten, wenn dies vermieden werden kann.

Um komplizierten Code zu vermeiden, müssen Sie Ihre Schnittstellen formalisieren, ~ 8 Mal mehr für das API-Design als für die Implementierung ausgeben (Stepanov schlug vor, mindestens das 10-fache für die Schnittstelle im Vergleich zur Implementierung auszugeben) und ein Projekt mit dem entsprechenden Wissen entwickeln Sie erstellen ein Projekt und schreiben nicht nur einen Algorithmus.

Ein Projekt umfasst API-Dokumentation, Funktionsdokumentation, Code- / Qualitätsmessungen, Projektmanagement usw. Bei keinem dieser Prozesse handelt es sich um einmalige, schnell auszuführende Schritte (alle benötigen Zeit, erfordern Voraussicht und Planung, und alle erfordern, dass Sie regelmäßig zu ihnen zurückkehren und sie mit Details überarbeiten / vervollständigen).

Anstatt dass andere Entwickler (einschließlich Sie selbst) den gesamten Algorithmus Zeile für Zeile lesen müssen, um herauszufinden, was er tut, können sie einfach den freundlichen beschreibenden Kommentar lesen, den Sie in einfachem Englisch geschrieben haben.

Ich würde dies als leichten Missbrauch von "Kommentaren" betrachten. Wenn der Programmierer etwas anstelle des gesamten Algorithmus lesen möchte , ist dies die Funktionsdokumentation. OK, die Funktionsdokumentation wird möglicherweise tatsächlich in Kommentaren in der Quelle angezeigt (möglicherweise zum Extrahieren mit Doc-Tools). Syntaktisch handelt es sich jedoch um einen Kommentar für Ihren Compiler. Sie sollten sie jedoch für unterschiedliche Zwecke betrachten. Ich denke nicht, dass "Kommentare sollten knapp sein" notwendigerweise "Dokumentation sollte knapp sein" oder sogar "Copyright-Vermerke sollten knapp sein" bedeutet!

Kommentare in der Funktion sind für jemanden lesbar , ebenso wie der Code. Wenn Ihr Code einige schwer verständliche Zeilen enthält und Sie diese nicht leicht verständlich machen können, ist ein Kommentar für den Leser hilfreich, um ihn als Platzhalter für diese Zeilen zu verwenden. Dies kann sehr nützlich sein, wenn der Leser nur versucht, das Wesentliche herauszufinden, aber es gibt ein paar Probleme:

• Kommentare sind nicht unbedingt wahr, wohingegen der Code das tut, was er tut. Der Leser nimmt Ihr Wort dafür und das ist nicht ideal.
• Der Leser versteht den Code selbst noch nicht. Bis er später darauf zurückkommt, ist er immer noch nicht qualifiziert, ihn zu ändern oder wiederzuverwenden. In welchem ​​Fall lesen sie es?

Es gibt Ausnahmen, aber die meisten Leser müssen den Code selbst verstehen. Kommentare sollten geschrieben werden, um dies zu unterstützen, und nicht, um es zu ersetzen. Aus diesem Grund wird empfohlen, dass in den Kommentaren angegeben wird, warum Sie es tun. Ein Leser, der die Motivation für die nächsten Codezeilen kennt, hat eine bessere Chance zu sehen, was er tut und wie.

Oft müssen wir komplizierte Dinge tun. Es ist sicherlich richtig, sie für das zukünftige Verständnis zu dokumentieren. Manchmal ist der richtige Ort für diese Dokumentation im Code, wo die Dokumentation mit dem Code auf dem neuesten Stand gehalten werden kann. Es lohnt sich aber auf jeden Fall, eine separate Dokumentation zu betrachten. Dies kann auch einfacher für andere Personen sein, einschließlich Diagrammen, Farbbildern und so weiter. Dann ist der Kommentar einfach:

// This code implements the algorithm described in requirements document 239.

oder auch nur

void doPRD239Algorithm() { ...

Sicherlich sind die Leute mit den Funktionen MatchStringKnuthMorrisPrattoder encryptAESoder zufrieden partitionBSP. Weitere undurchsichtige Namen sollten in einem Kommentar erläutert werden. Sie können auch bibliografische Daten und einen Link zu einem Artikel hinzufügen, aus dem Sie einen Algorithmus implementiert haben.

Wenn ein Algorithmus komplex und neuartig und nicht offensichtlich ist, ist er auf jeden Fall ein Dokument wert, auch wenn er nur für den internen Unternehmensumlauf bestimmt ist. Überprüfen Sie das Dokument in der Quellcodeverwaltung, wenn Sie befürchten, dass es verloren geht.

Es gibt eine andere Kategorie von Code, die weniger algorithmisch als bürokratisch ist. Sie müssen Parameter für ein anderes System einrichten oder mit den Fehlern eines anderen zusammenarbeiten:

/* Configure the beam controller and turn on the laser.
The sequence is timing-critical and this code must run with interrupts disabled.
Note that the constant 0xef45ab87 differs from the vendor documentation; the vendor
is wrong in this case.
Some of these operations write the same value multiple times. Do not attempt
to optimise this code by removing seemingly redundant operations.
*/

Ich vergesse, wo ich es gelesen habe, aber es gibt eine scharfe und klare Linie zwischen dem, was in Ihrem Code erscheinen soll und dem, was als Kommentar erscheinen soll.

Ich glaube, Sie sollten Ihre Absicht kommentieren, nicht Ihren Algorithmus . Ich kommentiere, was du vorhast, nicht was du tust .

Zum Beispiel:

// The getter.
public <V> V get(final K key, Class<V> type) {
  // Has it run yet?
  Future<Object> f = multitons.get(key);
  if (f == null) {
    // No! Make the task that runs it.
    FutureTask<Object> ft = new FutureTask<Object>(
            new Callable() {

              public Object call() throws Exception {
                // Only do the create when called to do so.
                return key.create();
              }

            });
    // Only put if not there.
    f = multitons.putIfAbsent(key, ft);
    if (f == null) {
      // We replaced null so we successfully put. We were first!
      f = ft;
      // Initiate the task.
      ft.run();
    }
  }
  try {
    /**
     * If code gets here and hangs due to f.status = 0 (FutureTask.NEW)
     * then you are trying to get from your Multiton in your creator.
     *
     * Cannot check for that without unnecessarily complex code.
     *
     * Perhaps could use get with timeout.
     */
    // Cast here to force the right type.
    return (V) f.get();
  } catch (Exception ex) {
    // Hide exceptions without discarding them.
    throw Throwables.asRuntimeException(ex);
  }
}

Hier gibt es keinen Versuch zu erklären , was jeder Schritt durchführt, alle heißt es ist , was es soll tun.

PS: Ich habe die Quelle gefunden, auf die ich mich bezog - Coding Horror: Code sagt Ihnen wie, Kommentare sagen Ihnen warum

Aber wir alle wissen, dass das nicht ausreicht.

"Ja wirklich?" Seit wann?

Gut gestalteter Code mit guten Namen ist in den allermeisten Fällen mehr als ausreichend. Die Argumente gegen die Verwendung von Kommentaren sind bekannt und dokumentiert (wie Sie sich beziehen).

Aber das sind Richtlinien (wie alles andere). In dem seltenen Fall (meiner Erfahrung nach etwa alle zwei Jahre), in dem sich die Situation verschlechtert, wenn sie (aufgrund von Leistungs- oder Kohäsionsanforderungen) in kleinere lesbare Funktionen umgewandelt wird, geben Sie einen ausführlichen Kommentar ein, in dem Sie erklären, was die Sache eigentlich ist tun (und warum Sie Best Practices verletzen).

Der Hauptzweck von Code besteht darin, einem Computer zu befehlen, etwas zu tun. Ein guter Kommentar ist also niemals ein Ersatz für guten Code, da Kommentare nicht ausgeführt werden können.

Abgesehen davon sind Kommentare in der Quelle eine Form der Dokumentation für andere Programmierer (einschließlich Sie selbst). Wenn es sich bei den Kommentaren um abstraktere Themen handelt, als der Code bei jedem Schritt tut, sind Sie besser als der Durchschnitt. Diese Abstraktionsstufe hängt vom verwendeten Tool ab. Kommentare, die Assembler-Routinen beigefügt sind, weisen im Allgemeinen eine niedrigere "Abstraktionsstufe" auf als beispielsweise diese APL A←0⋄A⊣{2⊤⍵:1+3×⍵⋄⍵÷2}⍣{⍺=A+←1}⎕. Ich denke, das wäre wahrscheinlich einen Kommentar über das Problem wert, das es lösen soll, hmmm?

Wenn der Code trivial ist, benötigt er keinen erklärenden Kommentar. Wenn der Code nicht trivial ist, ist der erläuternde Kommentar höchstwahrscheinlich auch nicht trivial.

Das Problem mit nicht-trivialer natürlicher Sprache ist, dass viele von uns nicht sehr gut darin sind, sie zu lesen oder zu schreiben. Ich bin mir sicher, dass Ihre schriftlichen Kommunikationsfähigkeiten ausgezeichnet sind, aber dennoch kann jemand mit einem geringeren Verständnis der geschriebenen Sprache Ihre Worte missverstehen.

Wenn Sie sich sehr bemühen, eine natürliche Sprache zu schreiben, die nicht falsch interpretiert werden kann, erhalten Sie so etwas wie ein juristisches Dokument (und wie wir alle wissen, sind diese Dokumente ausführlicher und schwer zu verstehen als Code).

Code sollte die prägnanteste Beschreibung Ihrer Logik sein, und es sollte nicht viel Debatte über die Bedeutung Ihres Codes geben, da Ihr Compiler und Ihre Plattform das letzte Wort haben.

Persönlich würde ich nicht sagen, dass Sie niemals einen Kommentar schreiben sollten. Nur, dass Sie sich überlegen sollten, warum Ihr Code einen Kommentar benötigt und wie Sie dies beheben können. Dies scheint ein häufiges Thema bei den Antworten zu sein.

Ein Punkt, der noch nicht erwähnt wurde, ist, dass es manchmal hilfreich sein kann, genau zu kommentieren, was ein Codeteil tut, wenn eine Sprache eine bestimmte Syntax für mehrere Zwecke verwendet. Angenommen, alle Variablen sind vom Typ float:

f1 = (float)(f2+f3); // Force result to be rounded to single precision
f4 = f1-f2;

Die Wirkung der explizit ein Gießens floatzu floatist das Ergebnis zu zwingen, mit einfacher Genauigkeit gerundet werden; Der Kommentar kann also so gesehen werden, als würde er einfach sagen, was der Code tut. Vergleichen Sie andererseits diesen Code mit:

thing.someFloatProperty = (float)(f2*0.1); // Divide by ten

Hier besteht der Zweck des Casts darin, zu verhindern, dass der Compiler auf die effizienteste Art und Weise quäkt (f2 / 10).

Ohne diesen Kommentar könnte jemand, der den vorherigen Code überprüft hat, der Meinung sein, dass die Besetzung fälschlicherweise hinzugefügt wurde, um zu verhindern, dass der Compiler quietscht, und dass sie nicht benötigt wird. Tatsächlich dient die Besetzung dem Zweck, genau das zu tun, was die Sprachspezifikation angibt: Das Ergebnis der Berechnung muss auf eine Genauigkeit gerundet werden, selbst bei Maschinen, bei denen das Runden teurer wäre als das Ergebnis auf einer höheren Genauigkeit zu halten. Angesichts der Tatsache, dass eine Besetzung von floateine Reihe von unterschiedlichen Bedeutungen und Zwecken haben kann, kann das Festlegen, welche Bedeutung in einem bestimmten Szenario beabsichtigt ist, dazu beitragen, klar zu machen, dass die tatsächliche Bedeutung mit der Absicht übereinstimmt.

Kommentare, die erklären, was der Code tut, sind eine Form der Vervielfältigung. Wenn Sie den Code ändern und dann vergessen, die Kommentare zu aktualisieren, kann dies zu Verwirrung führen. Ich sage nicht, benutze sie nicht, sondern benutze sie nur mit Bedacht. Ich abonniere die Maxime von Onkel Bob: "Nur kommentieren, was der Code nicht sagen kann".