Was ist selbstdokumentierender Code und kann er gut dokumentierten Code ersetzen? [geschlossen]

Ich habe einen Kollegen, der darauf besteht, dass sein Code keine Kommentare benötigt, sondern "selbstdokumentierend" ist.

Ich habe seinen Code überprüft, und obwohl er klarer ist als der Code, den andere erstellt haben, bin ich nicht der Meinung, dass selbstdokumentierender Code ebenso vollständig und nützlich ist wie kommentierter und dokumentierter Code.

Hilf mir, seinen Standpunkt zu verstehen .

• Was ist selbstdokumentierender Code?
• Kann es wirklich gut kommentierten und dokumentierten Code ersetzen?
• Gibt es Situationen, in denen es besser ist als gut dokumentierter und kommentierter Code?
• Gibt es Beispiele, bei denen Code ohne Kommentare möglicherweise nicht selbstdokumentierend sein kann?

Vielleicht sind es nur meine eigenen Grenzen, aber ich sehe nicht, wie es eine gute Praxis sein kann.

Dies ist kein Argument - bitte sprechen Sie keine Gründe an, warum gut kommentierter und dokumentierter Code hohe Priorität hat - es gibt viele Ressourcen, die dies zeigen, aber sie überzeugen meinen Kollegen nicht. Ich glaube, ich muss seine Perspektive besser verstehen, um ihn anders zu überzeugen. Starten Sie eine neue Frage, wenn Sie müssen, aber streiten Sie hier nicht.

Wow, schnelle Antwort! Bitte lesen Sie alle vorhandenen Antworten und geben Sie Kommentare zu den Antworten ab, anstatt neue Antworten hinzuzufügen, es sei denn, Ihre Antwort unterscheidet sich wirklich wesentlich von jeder anderen Antwort hier.

Diejenigen von Ihnen, die gegen selbstdokumentierenden Code argumentieren, sollen mir in erster Linie helfen, die Perspektive (dh die positiven Aspekte) selbstdokumentierender Code-Evangelisten zu verstehen. Ich gehe davon aus, dass andere Sie ablehnen werden, wenn Sie nicht beim Thema bleiben.

Meiner Meinung nach sollte sich jeder Code selbst dokumentieren. In gutem, selbst dokumentiertem Code müssen Sie nicht jede einzelne Zeile erklären, da jeder Bezeichner (Variable, Methode, Klasse) einen eindeutigen semantischen Namen hat. Wenn Sie mehr Kommentare als nötig haben, ist es tatsächlich schwieriger (!), Den Code zu lesen. Wenn also Ihr Kollege

• schreibt Dokumentationskommentare (Doxygen, JavaDoc, XML-Kommentare usw.) für jede Klasse, jedes Mitglied, jeden Typ und jede Methode AND
• kommentiert deutlich alle Teile des Codes, die sich nicht selbst dokumentieren UND
• schreibt einen Kommentar für jeden Codeblock, der die Absicht erklärt oder erklärt, was der Code auf einer höheren Abstraktionsebene tut (dh alle Dateien größer als 10 MB finden, anstatt alle Dateien in einem Verzeichnis zu durchlaufen, testen Sie, ob die Dateigröße größer als 10 ist MB, Rendite zurück, wenn wahr )

Sein Code und seine Dokumentation sind meiner Meinung nach in Ordnung. Beachten Sie, dass selbstdokumentierter Code nicht bedeutet, dass keine Kommentare vorhanden sein sollten, sondern nur, dass keine unnötigen Kommentare vorhanden sein sollten. Die Sache ist jedoch, dass durch das Lesen des Codes (einschließlich Kommentare und Dokumentationskommentare) ein sofortiges Verständnis dafür gewonnen werden sollte, was der Code tut und warum. Wenn das Verständnis des "selbstdokumentierenden" Codes länger dauert als der kommentierte Code, ist er nicht wirklich selbstdokumentierend.

Nun, da es sich um Kommentare und Code handelt, schauen wir uns einen tatsächlichen Code an. Vergleichen Sie diesen typischen Code:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Zu diesem selbstdokumentierenden Code, der zeigt, was getan wird:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Und dann zu diesem dokumentierten Code, der besser erklärt, warum er gemacht wird:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Und die endgültige Version des Codes als Dokumentation ohne Kommentare:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Hier ist ein Beispiel für einen schlechten Kommentarstil:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Im letzten Beispiel werden Kommentare verwendet, wenn Variablen stattdessen beschreibend benannt werden sollten, und die Ergebnisse einer Operation werden zusammengefasst, wenn wir klar erkennen können, um welche Operation es sich handelt. Ich würde das selbstdokumentierte zweite Beispiel jeden Tag diesem vorziehen, und vielleicht ist es das, worüber Ihr Freund spricht, wenn er selbstdokumentierten Code sagt.

Ich würde sagen, dass es vom Kontext Ihrer Tätigkeit abhängt. Für mich ist der selbstdokumentierte Code in diesem Fall wahrscheinlich ausreichend, aber ein Kommentar, der die Methodik hinter dem, was dahinter steckt (in diesem Beispiel die Gleichung), detailliert, ist ebenfalls nützlich.

Der Code selbst wird immer die aktuellste Erklärung dafür sein, was Ihr Code tut, aber meiner Meinung nach ist es sehr schwierig, die Absicht zu erklären , was der wichtigste Aspekt von Kommentaren ist. Wenn es richtig geschrieben ist, wissen wir bereits, was der Code tut, wir müssen nur wissen, warum um alles in der Welt es tut!

Jemand hat es einmal gesagt

1) Schreiben Sie nur Kommentare für Code, der schwer zu verstehen ist.
2) Versuchen Sie, keinen schwer verständlichen Code zu schreiben.

Die Idee hinter "selbstdokumentierendem" Code ist, dass die eigentliche Programmlogik im Code trivial klar genug ist, um jedem, der den Code liest, nicht nur zu erklären, was der Code tut, sondern auch, warum er es tut.

Meiner Meinung nach ist die Idee eines echten selbstdokumentierenden Codes ein Mythos. Der Code kann Ihnen die Logik hinter dem Geschehen erklären, aber er kann nicht erklären, warum dies auf eine bestimmte Weise geschieht, insbesondere wenn es mehr als eine Möglichkeit gibt, ein Problem zu lösen. Allein aus diesem Grund kann es niemals gut kommentierten Code ersetzen .

Ich denke, es ist wichtig zu hinterfragen, ob eine bestimmte Codezeile sich selbst dokumentiert, aber wenn Sie am Ende die Struktur und Funktion eines Codeschnitts nicht verstehen, helfen Kommentare meistens nicht. Nehmen Sie zum Beispiel amdfans Stück "richtig kommentierten" Codes:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Dieser Code ist in Ordnung, aber das Folgende ist in den meisten modernen Softwaresystemen gleichermaßen informativ und erkennt ausdrücklich an, dass die Verwendung einer Newtonschen Berechnung eine Wahl ist, die geändert werden kann, wenn ein anderes physikalisches Paradigma angemessener ist:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Nach meiner persönlichen Erfahrung gibt es nur sehr wenige "normale" Codierungssituationen, in denen Sie unbedingt Kommentare benötigen. Wie oft rollen Sie zum Beispiel Ihren eigenen Algorithmus? Grundsätzlich geht es bei allem anderen darum, Ihr System so zu strukturieren, dass ein Codierer die verwendeten Strukturen und die Auswahlmöglichkeiten, die das System zur Verwendung dieser bestimmten Strukturen veranlasst haben, verstehen kann.

Ich vergesse, woher ich das habe, aber:

Jeder Kommentar in einem Programm ist wie eine Entschuldigung an den Leser. "Es tut mir leid, dass mein Code so undurchsichtig ist, dass Sie ihn nicht verstehen können, wenn Sie ihn ansehen." Wir müssen nur akzeptieren, dass wir nicht perfekt sind, sondern uns bemühen, perfekt zu sein, und uns sofort entschuldigen, wenn wir müssen.

Zunächst ist es gut zu hören, dass der Code Ihres Kollegen tatsächlich klarer ist als der andere Code, den Sie gesehen haben. Es bedeutet, dass er wahrscheinlich nicht "Selbstdokumentation" als Entschuldigung dafür verwendet, zu faul zu sein, um seinen Code zu kommentieren.

Selbstdokumentierender Code ist Code, der keine Freitextkommentare erfordert, damit ein informierter Leser versteht, was er tut. Zum Beispiel ist dieser Code selbstdokumentierend:

print "Hello, World!"

und so ist das:

factorial n = product [1..n]

und so ist das:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Diese Idee eines "informierten Lesers" ist sehr subjektiv und situativ. Wenn Sie oder jemand anderes Probleme haben, dem Code Ihres Kollegen zu folgen, sollte er seine Vorstellung von einem informierten Leser neu bewerten. Es muss ein gewisses Maß an Vertrautheit mit der verwendeten Sprache und den verwendeten Bibliotheken vorausgesetzt werden, um die Selbstdokumentation des Codes aufzurufen.

Das beste Argument, das ich für das Schreiben von "selbstdokumentierendem Code" gesehen habe, ist, dass es das Problem vermeidet, dass Freitextkommentare nicht mit dem Code übereinstimmen, wie er geschrieben wird. Die beste Kritik ist, dass Code zwar beschreiben kann, was und wie er selbst tut, aber nicht erklären kann, warum etwas auf eine bestimmte Weise getan wird.

Selbstdokumentierender Code ist ein gutes Beispiel für "DRY" (Wiederholen Sie sich nicht). Duplizieren Sie keine Informationen in Kommentaren, die sich im Code selbst befinden oder befinden können.

Benennen Sie die Variable um, anstatt zu erklären, wofür eine Variable verwendet wird.

Anstatt zu erklären, was ein kurzer Codeausschnitt bewirkt, extrahieren Sie ihn in eine Methode und geben Sie ihm einen beschreibenden Namen (möglicherweise eine verkürzte Version Ihres Kommentartextes).

Anstatt zu erklären, was ein komplizierter Test bewirkt, extrahieren Sie dies auch in eine Methode und geben Sie ihr einen guten Namen.

Etc.

Danach erhalten Sie Code, der nicht so viel Erklärung erfordert, sondern sich selbst erklärt. Sie sollten daher die Kommentare löschen, die lediglich die Informationen im Code wiederholen.

Dies bedeutet nicht, dass Sie überhaupt keine Kommentare haben. Es gibt einige Informationen, die Sie nicht in den Code einfügen können, z. B. Informationen zur Absicht (das "Warum"). Im Idealfall ergänzen sich der Code und die Kommentare und fügen jeweils einen eindeutigen erklärenden Wert hinzu, ohne die Informationen im anderen zu duplizieren.

Selbstdokumentierender Code ist eine gute Praxis und kann bei richtiger Ausführung leicht die Bedeutung des Codes vermitteln, ohne zu viele Kommentare zu lesen. Besonders in Situationen, in denen die Domain von allen im Team gut verstanden wird.

Allerdings können Kommentare für Neuankömmlinge oder Tester oder zum Generieren von Dokumentations- / Hilfedateien sehr hilfreich sein.

Selbstdokumentierender Code + notwendige Kommentare tragen wesentlich dazu bei, Menschen in verschiedenen Teams zu helfen.

In Ordnung:

• Selbstdokumentierender Code ist Code, der dem Leser seine Absicht klar zum Ausdruck bringt.
• Nicht komplett. Kommentare sind immer hilfreich, um zu kommentieren, warum eine bestimmte Strategie gewählt wurde. Kommentare, die erklären, was ein Codeabschnitt tut, weisen jedoch auf Code hin, der sich nicht ausreichend selbst dokumentiert und möglicherweise umgestaltet werden muss.
• Kommentare lügen und sind veraltet. Code sagt immer, dass es wahrscheinlicher ist, die Wahrheit zu sagen.
• Ich habe noch nie einen Fall gesehen, in dem das Was des Codes ohne Kommentare nicht ausreichend klargestellt werden konnte. Wie ich bereits sagte, ist es jedoch manchmal notwendig / hilfreich, einen Kommentar zum Warum aufzunehmen .

Es ist jedoch wichtig zu beachten, dass wirklich selbstdokumentierender Code viel Selbst- und Teamdisziplin erfordert. Sie müssen lernen, deklarativer zu programmieren, und Sie müssen sehr bescheiden sein und "cleveren" Code zugunsten von Code vermeiden, der so offensichtlich ist, dass es den Anschein hat, als hätte ihn jeder schreiben können.

Wenn Sie einen "selbstdokumentierenden Code" lesen, sehen Sie, was er tut, aber Sie können nicht immer erraten, warum er auf diese bestimmte Weise funktioniert.

Es gibt Unmengen nicht programmierbarer Einschränkungen wie Geschäftslogik, Sicherheit, Benutzeranforderungen usw.

Wenn Sie Wartungsarbeiten durchführen, werden diese Backgorund-Informationen sehr wichtig.

Nur meine Prise Salz ...

Betrachten Sie zum einen das folgende Snippet:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

In diesem Beispiel haben Sie 5 Kommentarzeilen pro 3 Codezeilen. Schlimmer noch - die Kommentare fügen nichts hinzu, was Sie beim Lesen des Codes nicht sehen können. Wenn Sie 10 Methoden wie diese haben, können Sie "Kommentarblindheit" bekommen und nicht die eine Methode bemerken, die vom Muster abweicht.

Wenn natürlich eine bessere Version gewesen wäre:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Für trivialen Code bevorzuge ich es jedoch, keine Kommentare zu haben. Die Absicht und die gesamte Organisation werden in einem separaten Dokument außerhalb des Codes besser erläutert.

Der Unterschied besteht zwischen "was" und "wie".

• Sie sollten dokumentieren, "was" eine Routine tut.
• Sie sollten nicht dokumentieren, wie es funktioniert, es sei denn, es handelt sich um Sonderfälle (z. B. siehe ein bestimmtes Algorithmuspapier). Das sollte selbst dokumentiert sein.

Eine Sache, auf die Sie Ihren Kollegen möglicherweise hinweisen möchten, ist, dass unabhängig davon, wie selbstdokumentierend sein Code ist, Informationen verloren gehen, wenn andere alternative Ansätze in Betracht gezogen und verworfen werden, es sei denn, er kommentiert den Code mit diesen Informationen. Manchmal ist es genauso wichtig zu wissen, dass eine Alternative in Betracht gezogen wurde und warum dagegen entschieden wurde und dass Codekommentare im Laufe der Zeit am wahrscheinlichsten überleben.

In einer Firma, in der ich arbeitete, klebte eine der Programmiererinnen oben auf ihrem Monitor.

"Dokumentieren Sie Ihren Code wie die Person, die ihn verwaltet, ein homozidaler Verrückter, der weiß, wo Sie leben."

Selbstdokumentierender Code verwendet normalerweise Variablennamen, die genau mit dem Code übereinstimmen, sodass leicht zu verstehen ist, was vor sich geht

Ein solcher "selbstdokumentierender Code" ersetzt jedoch niemals Kommentare. Manchmal ist Code einfach zu komplex und selbstdokumentierender Code reicht nicht aus, insbesondere im Hinblick auf die Wartbarkeit.

Ich hatte einmal einen Professor, der fest an diese Theorie glaubte. Tatsächlich ist das Beste, woran ich mich erinnere, dass er sagte: "Kommentare sind für Weichlinge".
Es hat uns alle zuerst überrascht, aber es macht Sinn.
Die Situation ist jedoch so, dass Sie zwar verstehen können, was im Code vor sich geht, aber jemand, der weniger Erfahrung hat, möglicherweise hinter sich kommt und nicht versteht, was vor sich geht. Hier werden Kommentare wichtig. Ich weiß oft, dass wir nicht glauben, dass sie wichtig sind, aber es gibt nur sehr wenige Fälle, in denen Kommentare unnötig sind.

Ich bin überrascht, dass niemand " Literate Programming " hervorgebracht hat, eine Technik, die 1981 von Donald E. Knuth von TeX und "The Art of Computer Programming" entwickelt wurde.

Die Prämisse ist einfach: Da der Code von einem Menschen verstanden werden muss und Kommentare vom Compiler einfach weggeworfen werden, geben Sie jedem das, was er braucht - eine vollständige Textbeschreibung der Absicht des Codes, die nicht an die Anforderungen der Programmiersprache gebunden ist , für den menschlichen Leser und reinen Code für den Compiler.

Literate Programming Tools bieten dazu ein spezielles Markup für ein Dokument, das den Tools mitteilt, welcher Teil die Quelle sein soll und was Text ist. Das Programm reißt später die Quellcodeteile aus dem Dokument und stellt eine Codedatei zusammen.

Ich habe im Web ein Beispiel dafür gefunden: http://moonflare.com/code/select/select.nw oder die HTML-Version http://moonflare.com/code/select/select.html

Wenn Sie Knuths Buch darüber in einer Bibliothek finden (Donald E. Knuth, Literate Programming, Stanford, Kalifornien: Zentrum für das Studium von Sprache und Information, 1992, CSLI Lecture Notes, Nr. 27.), sollten Sie es lesen.

Das ist selbstdokumentierender Code, komplett mit Argumenten und allem. Macht sogar ein schönes Dokument, alles andere sind nur gut geschriebene Kommentare :-)

Ich möchte den vielen gültigen Antworten noch eine Perspektive bieten:

Was ist Quellcode? Was ist eine Programmiersprache?

Die Maschinen benötigen keinen Quellcode. Sie sind glücklich, Montage zu laufen. Programmiersprachen sind zu unserem Vorteil. Wir wollen keine Baugruppe schreiben. Wir müssen verstehen, was wir schreiben. Beim Programmieren geht es darum, Code zu schreiben.

Sollten Sie lesen können, was Sie schreiben?

Der Quellcode ist nicht in menschlicher Sprache geschrieben. Es wurde versucht (zum Beispiel FORTRAN), aber es ist nicht ganz erfolgreich.

Der Quellcode kann nicht mehrdeutig sein. Deshalb müssen wir mehr Struktur hineinstecken als mit Text. Text funktioniert nur mit Kontext, was für uns selbstverständlich ist, wenn wir Text verwenden. Der Kontext im Quellcode ist immer explizit. Denken Sie an "using" in C #.

Die meisten Programmiersprachen sind redundant, sodass der Compiler uns abfangen kann, wenn wir nicht kohärent sind. Andere Sprachen verwenden mehr Inferenz und versuchen, diese Redundanz zu beseitigen.

Typnamen, Methodennamen und Variablennamen werden von den Computern nicht benötigt. Sie werden von uns zur Referenzierung verwendet. Der Compiler versteht die Semantik nicht, das müssen wir verwenden.

Programmiersprachen sind eine sprachliche Brücke zwischen Mensch und Maschine. Es muss für uns beschreibbar und für sie lesbar sein. Sekundäre Forderungen sind, dass es für uns lesbar sein soll. Wenn wir gut in Semantik sind, wo es erlaubt ist, und gut darin sind, den Code zu strukturieren, sollte der Quellcode selbst für uns leicht zu lesen sein. Der beste Code benötigt keine Kommentare.

Aber Komplexität lauert in jedem Projekt. Sie müssen immer entscheiden, wo die Komplexität platziert werden soll und welche Kamele geschluckt werden sollen. Dies sind die Orte, an denen Kommentare verwendet werden können.

Selbstdokumentierender Code ist eine einfache Möglichkeit, das Problem zu lösen, dass Code, Kommentar und Dokumentation im Laufe der Zeit voneinander abweichen. Und es ist ein disziplinierender Faktor, klaren Code zu schreiben (wenn Sie so streng mit sich selbst sind).

Für mich sind dies die Regeln, die ich zu befolgen versuche:

• Der Code sollte so einfach und klar wie möglich zu lesen sein.
• Kommentare sollten Gründe für Entwurfsentscheidungen enthalten, die ich getroffen habe, z. B.: Warum verwende ich diesen Algorithmus oder Einschränkungen des Codes, z. B.: Funktioniert nicht, wenn ... (dies sollte in einem Vertrag / einer Zusicherung im Code behandelt werden) (normalerweise) innerhalb der Funktion / Prozedur).
• In der Dokumentation sollten die Verwendung (Aufruf von Konvertierungen), Nebenwirkungen und mögliche Rückgabewerte aufgeführt sein. Es kann mit Tools wie jDoc oder xmlDoc aus Code extrahiert werden. Es befindet sich daher normalerweise außerhalb der Funktion / Prozedur, aber in der Nähe des darin beschriebenen Codes.

Dies bedeutet, dass alle drei Mittel zur Dokumentation von Code nahe beieinander liegen und daher eher geändert werden, wenn sich der Code ändert, sich jedoch nicht in dem ausdrücken, was sie ausdrücken.

Das eigentliche Problem mit dem sogenannten selbstdokumentierenden Code ist, dass er vermittelt, was er tatsächlich tut. Während einige Kommentare jemandem helfen können, den Code besser zu verstehen (z. B. Schritte von Algorithmen usw.), ist er bis zu einem gewissen Grad überflüssig, und ich bezweifle, dass Sie Ihren Kollegen überzeugen würden.

Was in der Dokumentation jedoch wirklich wichtig ist, ist das, was aus dem Code nicht direkt ersichtlich ist: zugrunde liegende Absicht, Annahmen, Auswirkungen, Einschränkungen usw.

Auf einen Blick feststellen zu können, dass ein Code X ausführt, ist viel einfacher als festzustellen, dass ein Code Y nicht ausführt. Er muss Y dokumentieren ...

Sie könnten ihm ein Beispiel für einen Code zeigen, der gut aussieht, offensichtlich ist, aber nicht alle Grundlagen der Eingabe abdeckt, und sehen, ob er ihn findet.

Ich denke, dass selbstdokumentierender Code ein guter Ersatz für das Kommentieren ist. Wenn Sie Kommentare benötigen, um zu erklären, wie oder warum Code so ist, wie er ist, haben Sie eine Funktion oder Variablennamen, die zur Erläuterung geändert werden sollten. Es kann jedoch Sache des Codierers sein, ob er das Defizit mit einem Kommentar ausgleicht oder einige Variablen und Funktionen umbenennt und Code umgestaltet.

Es kann Ihre Dokumentation jedoch nicht wirklich ersetzen, da Sie anderen Dokumentationen geben, um zu erklären, wie Sie Ihr System verwenden, anstatt wie es Dinge tut.

Bearbeiten: Ich (und wahrscheinlich alle anderen) sollte wahrscheinlich die Bestimmung haben, dass eine DSP-App (Digital Signal Processing) sehr gut kommentiert werden sollte. Dies liegt hauptsächlich daran, dass DSP-Apps im Wesentlichen 2 für Schleifen sind, die mit Arrays von Werten gespeist werden und diese Werte addieren / multiplizieren / usw. ... um das Programm zu ändern, ändern Sie die Werte in einem der Arrays ... benötigen einige Kommentare, um zu sagen, was du machst in diesem Fall;)

Beim Schreiben von mathematischem Code fand ich es manchmal nützlich, lange, essayartige Kommentare zu schreiben, in denen die Mathematik, die vom Code verwendeten Notationskonventionen und die Zusammenhänge erläutert werden. Wir sprechen hier von Hunderten von Dokumentationszeilen.

Ich versuche, meinen Code so selbstdokumentierend wie möglich zu gestalten, aber wenn ich nach ein paar Monaten wieder daran arbeite, muss ich die Erklärung wirklich lesen, um keinen Hash daraus zu machen.

Natürlich ist diese Art von extremer Maßnahme in den meisten Fällen nicht erforderlich. Ich denke, die Moral der Geschichte lautet: Unterschiedlicher Code erfordert unterschiedliche Dokumentationsmengen. Einige Codes können so klar geschrieben werden, dass sie keine Kommentare benötigen - schreiben Sie sie also so klar und verwenden Sie dort keine Kommentare!

Viele Codes benötigen jedoch Kommentare, um einen Sinn zu ergeben. Schreiben Sie sie daher so klar wie möglich und verwenden Sie dann so viele Kommentare, wie sie benötigen ...

Ich würde - wie viele von Ihnen - argumentieren, dass Code, um wirklich selbstdokumentierend zu sein, irgendeine Form von Absicht zeigen muss. Aber ich bin überrascht, dass noch niemand BDD erwähnt hat - Behavior Driven Development . Ein Teil der Idee ist, dass Sie automatisierte Tests (Code) haben, die die Absicht Ihres Codes erklären, was sonst so schwer zu erkennen ist.

Gute Domain-Modellierung 
+ gute Namen (Variablen, Methoden, Klassen) 
+ Codebeispiele (Unit-Tests aus Anwendungsfällen) 
= selbstdokumentierende Software 

Einige Gründe, warum zusätzliche Kommentare zusätzlich zum Code klarer sein könnten:

• Der Code, den Sie sich ansehen, wurde automatisch generiert, und daher können Änderungen am Code beim nächsten Kompilieren des Projekts möglicherweise blockiert werden
• Eine weniger einfache Implementierung wurde gegen einen Leistungsgewinn eingetauscht (Abrollen einer Schleife, Erstellen einer Nachschlagetabelle für eine teure Berechnung usw.)

Es wird alles in dem sein, was das Team in seiner Dokumentation schätzt. Ich würde vorschlagen, dass das Dokumentieren von Warum / Absicht anstelle von Wie wichtig ist und dies nicht immer im selbstdokumentierenden Code erfasst wird. get / set nein diese sind offensichtlich - aber Berechnung, Abruf usw. etwas vom Warum sollte ausgedrückt werden.

Beachten Sie auch die Unterschiede in Ihrem Team, wenn Sie aus verschiedenen Nationalitäten stammen. Unterschiede in der Diktion können sich in der Benennung von Methoden niederschlagen:

BisectionSearch

Binäre Suche

BinaryChop

Diese drei Methoden von Entwicklern, die auf drei verschiedenen Kontinenten geschult wurden, machen dasselbe. Nur durch Lesen der Kommentare, die den Algorithmus beschrieben, konnten wir die Duplizierung in unserer Bibliothek identifizieren.

Für mich ist das Lesen von Code, der Kommentare benötigt, wie das Lesen von Text in der Sprache, die ich nicht kenne. Ich sehe eine Aussage und verstehe nicht, was sie tut oder warum - und ich muss mir die Kommentare ansehen. Ich lese einen Satz und muss im Wörterbuch nachsehen, um zu verstehen, was er bedeutet.

Es ist normalerweise einfach, Code zu schreiben, der selbst dokumentiert, was er tut. Um Ihnen zu sagen, warum dies so ist, sind Kommentare besser geeignet, aber auch hier kann Code besser sein. Wenn Sie Ihr System auf jeder Abstraktionsebene verstehen, sollten Sie versuchen, Ihren Code wie folgt zu organisieren

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Wo der Methodenname Ihre Absicht widerspiegelt und der Methodenkörper erklärt, wie Sie Ihr Ziel erreichen. Sie können ohnehin nicht das gesamte Buch im Titel erzählen, daher müssen noch die wichtigsten Abstraktionen Ihres Systems sowie komplexe Algorithmen, nicht triviale Methodenverträge und Artefakte dokumentiert werden.

Wenn der Code, den Ihr Kollege erstellt, wirklich selbst dokumentiert ist, haben Sie Glück. Wenn Sie der Meinung sind, dass der Code Ihrer Kollegen Kommentare benötigt, müssen Sie dies tun. Öffnen Sie einfach den nicht trivialsten Ort darin, lesen Sie ihn einmal und sehen Sie, ob Sie alles verstanden haben oder nicht. Wenn der Code selbst dokumentiert ist, sollten Sie dies tun. Wenn nicht - stellen Sie Ihrem Kollegen eine Frage, nachdem er Ihnen eine Antwort gegeben hat, fragen Sie, warum diese Antwort zuvor nicht in Kommentaren oder Code dokumentiert wurde. Er kann behaupten, dass Code für eine so kluge Person wie ihn selbst dokumentiert ist, aber er muss trotzdem andere Teammitglieder respektieren - wenn Ihre Aufgaben das Verständnis seines Codes erfordern und sein Code Ihnen nicht alles erklärt, was Sie verstehen müssen - es braucht Bemerkungen.

Die meisten Dokumentationen / Kommentare dienen dazu, zukünftige Code-Enhancer / Entwickler zu unterstützen, wodurch der Code wartbar wird. Meistens kehren wir zu einem späteren Zeitpunkt zu unserem Modul zurück, um neue Funktionen hinzuzufügen oder zu optimieren. Zu diesem Zeitpunkt wäre es einfacher, den Code durch einfaches Lesen der Kommentare zu verstehen, als durch zahlreiche Haltepunkte zu gehen. Außerdem würde ich lieber Zeit damit verbringen, über neue Logik nachzudenken, als die vorhandene zu entschlüsseln.

Ich denke, was er erreichen könnte, ist, dass wenn Kommentare erklären, was der Code tut, er neu geschrieben werden sollte, um klar zu sein, was seine Absicht ist. Das meint er mit selbstdokumentierendem Code. Oft kann dies bedeuten, lange Funktionen einfach in logische kleinere Teile mit einem beschreibenden Funktionsnamen aufzuteilen.

Das bedeutet nicht, dass der Code nicht kommentiert werden sollte. Dies bedeutet, dass Kommentare einen Grund dafür liefern sollten, warum der Code so geschrieben ist, wie er ist.

Ich glaube, Sie sollten immer danach streben, selbstdokumentierenden Code zu erhalten, da dies das Lesen von Code erleichtert. Man muss aber auch pragmatisch sein.

Zum Beispiel füge ich normalerweise jedem Klassenmitglied einen Kommentar hinzu (ich verwende dafür Dokumentationskommentare). Dies beschreibt, was das Mitglied tun soll, aber nicht, wie es es tut. Ich finde, wenn ich Code durchlese, insbesondere alten Code, kann ich mich schnell daran erinnern, wofür das Mitglied ist, und ich finde es auch einfacher, als den Code zu lesen und ihn auszuarbeiten, insbesondere wenn der Codefluss ziemlich stark herumspringt .

Dies ist nur meine Meinung. Ich kenne viele Leute, die überhaupt ohne Kommentare arbeiten und sagen, dass sie dies für kein Problem halten. Ich habe jedoch jemanden nach einer Methode gefragt, die er vor sechs Monaten geschrieben hat, und er musste einige Minuten nachdenken, um mir genau zu sagen, was sie tat. Dies ist kein Problem, wenn die Methode kommentiert wird.

Schließlich müssen Sie bedenken, dass Kommentare ebenso Teil des Systems sind wie Code. Während Sie die Funktionalität umgestalten und ändern, müssen Sie auch Ihre Kommentare aktualisieren. Dies ist ein Argument gegen die Verwendung von Kommentaren, da sie schlimmer als nutzlos sind, wenn sie falsch sind.