it-swarm.com.de

Was ist selbstdokumentierender Code und kann er gut dokumentierten Code ersetzen?

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 produzieren, bin ich dennoch anderer Meinung, dass selbstdokumentierender Code ebenso vollständig und nützlich ist wie kommentierter und dokumentierter Code.

Hilf mir zu verstehen sein Standpunkt.

  • 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, in denen Code ohne Kommentare nicht selbstdokumentierend sein kann?

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

Dies ist kein Argument - bitte erwähnen Sie nicht, warum gut kommentierter und dokumentierter Code hohe Priorität hat - es gibt viele Quellen, die dies belegen, aber sie überzeugen meine Kollegen nicht. Ich glaube, ich muss seine Perspektive besser verstehen, um ihn von etwas anderem zu überzeugen. Beginnen 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 an, anstatt neue Antworten hinzuzufügen, es sei denn, Ihre Antwort unterscheidet sich wesentlich von jeder anderen Antwort hier.

Diejenigen unter 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, wenn Sie nicht beim Thema bleiben.

248
Adam Davis

Meiner Meinung nach sollte sich jeder Code selbst dokumentieren. In gutem, selbstdokumentiertem Code müssen Sie nicht jede einzelne Zeile erklären, da jeder Bezeichner (Variable, Methode, Klasse) eine eindeutige Semantik hat Name. 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 UND
  • kommentiert deutlich alle Teile des Codes, die kein selbstdokumentierendes UND sind
  • schreibt einen Kommentar für jeden Codeblock, der die Absicht erklärt, oder was der Code auf einer höheren Abstraktionsebene tut (dh findet alle Dateien, die größer als 10 MB sind Anstatt alle Dateien in einem Verzeichnis zu durchlaufen, testen Sie, ob die Dateigröße größer als 10 MB ist, und geben Sie return zurück, wenn true )

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

170
OregonGhost

Nun, da es um Kommentare und Code geht, schauen wir uns einen aktuellen 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, dass was ausgeführt wird:

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

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

/* 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 von Code als Dokumentation mit null Kommentaren benötigt:

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 stattdessen Variablen beschreibend benannt werden sollten, und die Ergebnisse einer Operation werden zusammengefasst, wenn klar erkennbar ist, um welche Operation es sich handelt. Ich würde jeden Tag das selbstdokumentierte zweite Beispiel dem vorziehen, und vielleicht ist es das, worüber Ihr Freund spricht, wenn er selbstdokumentierten Code sagt.

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

375
ine

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

168
andygeers

Jemand sagte einmal

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

92
Loofer

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

Meiner Meinung nach ist die Idee eines sich selbst dokumentierenden Codes ein Mythos. Der Code kann Ihnen die Logik erklären, die dahinter steckt, aber er kann nicht erklären, warum dass dies auf eine bestimmte Weise geschieht, insbesondere wenn es mehr als eine Möglichkeit gibt, ein Problem zu lösen. Schon aus diesem Grund kann es niemals gut kommentiert Code ersetzen.

36
Scott Dorman

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 die meisten Kommentare nicht weiter. Nehmen Sie zum Beispiel amdfans Slice "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, falls 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 beispielsweise Ihren eigenen Algorithmus? Im Grunde geht es bei allem anderen darum, Ihr System so zu strukturieren, dass ein Codierer die verwendeten Strukturen und die Entscheidungen, die das System zur Verwendung dieser bestimmten Strukturen veranlasst haben, nachvollziehen kann.

18
Mike Burton

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 beim Betrachten nicht verstehen können". Wir müssen einfach akzeptieren, dass wir nicht perfekt sind, sondern uns bemühen, perfekt zu sein und uns zu entschuldigen, wenn es nötig ist.

16
EBGreen

Selbstdokumentierender Code ist ein gutes Beispiel für "DRY" (Don't Repeat Yourself). 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 ausführlich erklärt werden muss. Daher sollten Sie die Kommentare löschen, die lediglich 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 in den anderen zu duplizieren.

14
Wedge

selbstdokumentierender Code ist eine gute Praxis und kann bei richtiger Ausführung leicht die Bedeutung des Codes wiedergeben, ohne zu viele Kommentare zu lesen. insbesondere in Situationen, in denen die Domäne von allen im Team gut verstanden wird.

Allerdings können Kommentare für Neueinsteiger oder für Tester sehr hilfreich sein oder um Dokumentations-/Hilfedateien zu generieren.

selbstdokumentierender Code + notwendige Kommentare helfen den Leuten in allen Teams.

13
Gulzar Nazim

Zuallererst ist es gut zu hören, dass der Code Ihres Kollegen tatsächlich klarer ist als der anderer Code, den Sie gesehen haben. Das bedeutet, dass er "Selbstdokumentation" wahrscheinlich nicht als Ausrede dafür benutzt, 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. Dieser Code ist beispielsweise 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 Vorstellung eines "informierten Lesers" ist sehr subjektiv und situativ. Wenn Sie oder jemand anderes Probleme haben, den Code Ihres Kollegen zu befolgen, sollte er seine Vorstellung von einem informierten Leser überdenken. Es muss ein gewisser Grad an Vertrautheit mit der verwendeten Sprache und den verwendeten Bibliotheken vorausgesetzt werden, um den Code selbstdokumentierend aufzurufen.

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

13
Steven Huwig

In Ordnung:

  • Selbstdokumentierender Code ist Code, der dem Leser seine Absicht deutlich macht.
  • Nicht komplett. Kommentare sind immer hilfreich für Kommentare zu warum einer bestimmten Strategie wurde gewählt. Kommentare, die erklären was, was ein Codeabschnitt gerade tut, weisen jedoch auf Code hin, der sich nicht ausreichend selbst dokumentiert und überarbeitet werden könnte.
  • Kommentare lügen und veralten. Code erzählt immer ist eher die Wahrheit zu sagen.
  • Ich habe noch nie einen Fall gesehen, in dem das was von Code ohne Kommentare nicht ausreichend klargestellt werden konnte. Wie ich bereits sagte, ist es manchmal notwendig/hilfreich, einen Kommentar zum warum hinzuzufügen.

Es ist jedoch wichtig zu wissen, dass ein wirklich selbstdokumentierender Code viel Selbst- und Teamdisziplin erfordert. Man muss lernen, deklarativer zu programmieren, und man muss sehr bescheiden sein und "cleveren" Code zugunsten von Code vermeiden, der so offensichtlich ist, dass es den Anschein hat, als hätte jemand ihn geschrieben.

9
Avdi

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 einfachen Code bevorzuge ich jedoch, keine Kommentare zu haben. Die Absicht und die Gesamtorganisation werden in einem separaten Dokument außerhalb des Codes besser erläutert.

6
ddimitrov

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 unzählige nicht programmierbare Einschränkungen wie Geschäftslogik, Sicherheit, Benutzeranforderungen usw.

Wenn Sie Wartungsarbeiten durchführen, werden diese Hintergrundinformationen sehr wichtig.

Nur meine Prise Salz ...

6
ulm

Der Unterschied liegt 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. beziehen Sie sich auf ein bestimmtes Algorithmuspapier). Das sollte selbst dokumentiert sein.
5
Stefano Borini

Haben Sie von Donald Knuths "WEB" -Projekt zur Umsetzung seines Literate Programming -Konzepts gehört? Es ist mehr als selbstdokumentierender Code. Es ist eher eine Dokumentation, die als Code kompiliert und ausgeführt werden kann. Ich weiß allerdings nicht, wie viel es heute verwendet wird.

5
catfood

In einer Firma, in der ich arbeitete, hatte eine der Programmiererinnen die folgenden Probleme auf ihrem Monitor.

"Dokumentieren Sie Ihren Code so, wie die Person, die ihn verwaltet, ein homozidaler Wahnsinniger ist, der weiß, wo Sie leben."

5
JoeOD

Möglicherweise möchten Sie Ihren Kollegen darauf hinweisen, dass, unabhängig davon, wie selbstdokumentierend sein Code ist, andere alternative Ansätze in Betracht gezogen und verworfen werden, diese Informationen verloren gehen, wenn er den Code nicht mit diesen Informationen kommentiert. Manchmal ist es genauso wichtig zu wissen, dass eine Alternative in Betracht gezogen wurde und warum sie abgelehnt wurde und Code-Kommentare mit der Zeit am wahrscheinlichsten überleben.

5

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

Die Prämisse ist einfach: Da der Code von einem Menschen verstanden werden muss und Kommentare vom Compiler einfach weggeworfen werden, warum nicht jedem das Nötige geben - eine vollständige textuelle Beschreibung der Absicht des Codes, ungebunden von den Anforderungen der Programmiersprache? , für den menschlichen Leser und reinen Code für den Compiler.

Zu diesem Zweck geben Sie den Tools für die Literate-Programmierung ein spezielles Markup für ein Dokument, in dem angegeben ist, welcher Teil die Quelle sein soll und was Text ist. Das Programm reißt später die Quelltextteile aus dem Dokument und stellt eine Codedatei zusammen.

Ich habe ein Beispiel im Internet 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 Argumentation und allem. Auch macht ein schönes Dokument, alles andere ist nur gut geschriebene Kommentare :-)

4

Die Sichtweise, dass Code sich selbst dokumentiert, macht mich verrückt. Eine bestimmte Codezeile oder ein untergeordneter Algorithmus kann sich zwar selbst dokumentieren, aber der Zweck im übergeordneten Bild ist es einfach nicht.

Ich war vor ein oder zwei Monaten so frustriert darüber, dass ich einen ganzen Blog-Post geschrieben habe, der meine Sichtweise beschreibt. hier posten .

4
JaredPar

Meine Ansicht ist in diesem Beitrag geschrieben:

Der einzige Tipp, um Ihren Code zu dokumentieren.

Auszug:

Anstatt viele Kommentare zu verfassen, um die subtilen Verhaltensweisen Ihres Programms zu erläutern, sollten Sie Ihre Logik so umstrukturieren, dass sie selbstverständlich ist. Anstatt zu dokumentieren, was eine Methode tut, wählen Sie einen eindeutigen Namen für diese Methode. Warum nicht einfach eine NotImplementedException () auslösen, anstatt Ihren Code zu markieren, um unfertige Arbeiten anzuzeigen? Anstatt sich Sorgen zu machen, ob Ihre Kommentare für Ihren Chef, Ihre Kollegen oder jeden, der den Code liest, höflich genug klingen, sollten Sie nicht einfach aufhören, sich Sorgen zu machen, indem Sie sie überhaupt nicht schreiben.

Je klarer Ihr Code ist, desto einfacher ist es, ihn zu pflegen, zu erweitern und an zukünftigen Ausgaben zu arbeiten. Je weniger anspruchsvoll Ihr Code ist, desto weniger müssen Sie ihn kommentieren. Je mehr Kommentare, desto höher die Wartungskosten.

4
Graviton

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

Was ist Quellcode? Was ist eine Programmiersprache?

Die Maschinen benötigen keinen Quellcode. Sie freuen sich, Assembly zu leiten. Programmiersprachen sind zu unserem Vorteil. Wir wollen keine Versammlung schreiben. Wir müssen verstehen, was wir schreiben. Beim Programmieren geht es darum, Code zu schreiben.

Solltest du lesen können, was du schreibst?

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

Quellcode kann keine Mehrdeutigkeit aufweisen. Deshalb müssen wir mehr Struktur in sie einfügen als wir es mit Text tun. Text funktioniert nur mit Kontext, den wir als gegeben ansehen, wenn wir Text verwenden. Der Kontext im Quellcode ist immer explizit. Denken Sie an "using" in C #.

Die meisten Programmiersprachen haben Redundanz, so dass der Compiler uns fangen 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 ist für uns zu gebrauchen.

Programmiersprachen sind eine sprachliche Brücke zwischen Mensch und Maschine. Es muss für uns schreibbar und für sie lesbar sein. Sekundäre Anforderungen sind, dass es für uns lesbar sein soll. Wenn wir in der Semantik gut sind und den Code gut strukturieren können, sollte der Quellcode auch für uns leicht lesbar sein. Der beste Code benötigt keine Kommentare.

In jedem Projekt lauert jedoch Komplexität. Sie müssen sich immer entscheiden, wo die Komplexität abgelegt werden soll und welche Kamele geschluckt werden sollen. Dies sind die Stellen, an denen Kommentare verwendet werden können.

4
Guge

selbstdokumentierender Code verwendet normalerweise Variablennamen, die genau dem entsprechen, was der Code tut, so dass 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 erinnern kann, dass er gesagt hat: "Kommentare sind für Weichlinge".
Zuerst hat es uns alle überrascht, aber es macht Sinn.
Die Situation ist jedoch so, dass Sie, obwohl Sie möglicherweise verstehen können, was im Code vor sich geht, jemanden, der weniger erfahren ist, möglicherweise hinter sich bringen und nicht verstehen, was vor sich geht. Hier werden Kommentare wichtig. Ich weiß oft, dass wir nicht glauben, dass sie wichtig sind, aber es gibt sehr wenige Fälle, in denen Kommentare unnötig sind.

4
Josh Mein

Beim Schreiben von mathematischem Code habe ich es manchmal nützlich gefunden, lange, essayartige Kommentare zu schreiben, die die Mathematik, die vom Code verwendeten Konventionen und die Zusammenhänge erklären. Wir sprechen hier über Hunderte 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 unbedingt lesen, um keinen Hash daraus zu machen.

Natürlich ist eine solche extreme 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 ...

3
comingstorm

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, sollten Sie eine Funktion oder Variablennamen ändern, um die Erklärung zu erleichtern. Es kann jedoch Sache des Programmierers sein, ob er die Lücke mit einem Kommentar schließt oder einige Variablen und Funktionen umbenennt und den Code umgestaltet.

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

Bearbeiten: Ich (und wahrscheinlich jeder andere) sollte wahrscheinlich die Bestimmung haben, dass eine DSP-App (Digital Signal Processing) sehr gut kommentiert werden sollte. Das liegt hauptsächlich daran, dass DSP-Apps im Wesentlichen 2 für Schleifen sind, die mit Arrays von Werten und Additionen/Multiplikationen/usw. gespeist werden. Um das Programm zu ändern, müssen Sie die Werte in einem der Arrays ändern das machst du in dem fall;)

3
workmad3

Selbstdokumentierender Code ist eine einfache Lösung für das Problem, dass sich Code, Kommentar und Dokumentation im Laufe der Zeit unterscheiden. 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 Designentscheidungen angeben, die ich getroffen habe, wie: Warum verwende ich diesen Algorithmus oder Einschränkungen des Codes, wie: Funktioniert nicht, wenn ... (dies sollte in einem Vertrag/einer Zusicherung im Code behandelt werden) (normalerweise) innerhalb der Funktion/Prozedur).
  • Die Dokumentation sollte die Verwendung (Aufruf von Converntions), Nebenwirkungen und mögliche Rückgabewerte auflisten. Es kann mit Tools wie jDoc oder xmlDoc aus dem Code extrahiert werden. Es befindet sich daher normalerweise außerhalb der Funktion/Prozedur, aber in der Nähe des beschriebenen Codes.

Dies bedeutet, dass alle drei Mittel zur Codedokumentation eng beieinander liegen und daher mit größerer Wahrscheinlichkeit geändert werden, wenn sich der Code ändert, sich jedoch nicht in dem überlappen, was sie ausdrücken.

3

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. Algorithmusschritte usw.), ist er zu einem gewissen Grad überflüssig, und ich bezweifle, dass Sie Ihren Kollegen überzeugen würden.

Was jedoch in der Dokumentation wirklich wichtig ist, ist das Material, das nicht direkt aus dem Code hervorgeht: zugrunde liegende Absichten, 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 ...

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

3
Uri

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

 Gute Domain-Modellierung 
 + Gute Namen (Variablen, Methoden, Klassen) 
 + Codebeispiele (Komponententests aus Anwendungsfällen) 
 = Selbstdokumentierende Software 
3
Torbjørn

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

  • Der Code, den Sie sich ansehen, wurde automatisch generiert, sodass Änderungen am Code beim nächsten Kompilieren des Projekts möglicherweise nicht mehr möglich sind
  • Eine weniger unkomplizierte Implementierung wurde gegen einen Leistungsgewinn eingetauscht (Abwickeln einer Schleife, Erstellen einer Nachschlagetabelle für eine teure Berechnung usw.).
2
John

Es wird alles in dem sein, was das Team in seiner Dokumentation schätzt. Ich würde vorschlagen, zu dokumentieren, warum/Absicht statt wie wichtig ist, und dies wird nicht immer in selbstdokumentierendem Code erfasst. get/set nein das liegt auf der hand - aber rechnen, abrufen etc sowas von warum sollte man ausdrücken.

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

BisectionSearch

Binäre Suche

BinaryChop

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

2
MikeJ

// wenn es kein biggie ist, ärgere dich nicht darüber.

// Wenn Sie überall Kommentare schreiben, werden die wichtigen nicht gesehen

  • Methode Parameter Bemerkung: Muss sterben. Dies ist Code-Duplikation.

// Parameter sollten selbsterklärend sein.

  • WTF-Faktor Phantasie: Wird jemand, einschließlich mir, WTF dazu sagen?
2
conan

Die meisten Dokumentationen/Kommentare dienen dazu, zukünftige Code-Optimierer/-Entwickler dabei zu unterstützen, den Code wartbar zu machen. Meistens werden wir zu einem späteren Zeitpunkt wieder zu unserem Modul zurückkehren, um neue Funktionen hinzuzufügen oder zu optimieren. Zu diesem Zeitpunkt ist es einfacher, den Code durch einfaches Lesen der Kommentare zu verstehen, als zahlreiche Haltepunkte zu durchlaufen. Außerdem würde ich lieber Zeit damit verbringen, über neue Logik nachzudenken, als das Bestehende zu entziffern.

2
s y

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

Normalerweise ist es einfach, Code zu schreiben, der selbst dokumentiert, was er tut. Um Ihnen zu erklären, 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 wiedergeben, weshalb die wichtigsten Abstraktionen Ihres Systems noch dokumentiert werden müssen sowie komplexe Algorithmen, nicht triviale Methodenverträge und Artefakte.

Wenn der Code, den Ihr Kollege produziert, wirklich selbst dokumentiert ist, haben Sie und er Glück. Wenn Sie der Meinung sind, dass der Code Ihrer Kollegen Kommentare benötigt, ist dies erforderlich. Öffnen Sie einfach die nicht-triviale Stelle darin, lesen Sie sie 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, und 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 ein Selbstdokument ist, aber er muss auf jeden Fall andere Teammitglieder respektieren - wenn Ihre Aufgaben Verständnis für seinen Code erfordern und sein Code Ihnen nicht alles erklärt, was Sie verstehen müssen -, muss es sein Bemerkungen.

2
Pavel Feldman

Eine gute Entwurfsstruktur weist darauf hin, dass einige Funktionen für den allgemeinen Gebrauch und einige für die zufällige Geschäftslogik vorgesehen sind, obwohl Sie keinen Kommentar haben, der besagt, dass "diese Funktion allgemein ist".

Wir sollten jedoch die Dokumentation von Design und Spezifikation nicht vergessen. Diese haben oder sollten zumindest einen Großteil der Texte haben, die in Kommentaren nicht unbedingt benötigt werden. Software hat oft auch Benutzerhandbücher und andere Beschreibungsdokumente, und diese sollten mit dem, was das Programm tut, synchronisiert sein. Die Situation ist nicht großartig, wenn der Benutzer herausfinden muss, was die Software anstelle eines Handbuchs aus dem Quellcode macht. Selbstdokumentierender Code bedeutet also nicht, dass die eigentliche Software dokumentiert wurde.

Denken Sie auch an die Rückverfolgbarkeit von Features. Wenn Sie Ihr Handbuch haben, sollten Sie in der Lage sein, die Funktionen für eine bessere Wartbarkeit bis zum Quellcode und zurück zu verfolgen. Bei Handbüchern und Spezifikationen geht es nicht so sehr um Programmierung, sondern um Software-Engineering. Je größer die Software, desto mehr Engineering wird benötigt.

1
Silvercode

Wenn Ihr Code ohne Kommentare nicht vollständig klar ist, gibt es Raum, Ihren Code zu verbessern.

Ich sage nicht "nicht unklaren Code kommentieren". Ich sage "Machen Sie Ihren Code klar".

Wenn Sie Ihren Code in irgendeiner Weise unklar lassen, dann verwenden Sie Kommentare, um dies zu kompensieren.

1
Jay Bazuzi

Einige Perspektiven aus dem nicht kommentierenden Lager.

"Gut kommentierter" (ausführlicher) Code ist schwerer zu lesen und zu verstehen. Zum einen muss einfach mehr Text gescannt werden. Dies erhöht den kognitiven Aufwand für das Verständnis einer CodeBase - der nicht funktionierende Text belegt Platz auf dem Bildschirm, der zum Anzeigen von Code verwendet werden könnte.

Ein weiteres großes Problem bei Kommentaren besteht darin, dass sie unzuverlässig sind - insbesondere bei älteren Codebasen setzt comment rot schneller ein als bit rot.

Und dann gibt es natürlich die Mühe, Kommentare zu schreiben. Mit Ausnahme der gelegentlichen einzeiligen Klärung bekomme ich jedes Mal, wenn ich anfange, Code zu kommentieren, eines von zwei Schuldgefühlen

  1. diese Informationen müssen in die allgemeine Dokumentation aufgenommen werden
  2. Ich muss meinen Code bereinigen
1
Scott Weinstein

Ich denke, was er damit anfangen 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. Dies kann oft bedeuten, lange Funktionen einfach in logische kleinere Teile mit einem beschreibenden Funktionsnamen aufzuteilen.

Das heißt nicht, dass der Code nicht kommentiert werden sollte. Das bedeutet, dass Kommentare einen Grund liefern sollten, warum der Code so geschrieben ist, wie er ist.

1
Korbin

Ich bin der Meinung, dass Sie sich immer bemühen sollten, selbstdokumentierenden Code zu erstellen, 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 dazu Dokumentationskommentare). Dies beschreibt, was das Mitglied tun soll, aber nicht, wie es es tut. Ich stelle fest, dass ich mich beim Lesen von Code, insbesondere von altem Code, schnell daran erinnere, wofür das Mitglied ist, und ich finde es auch einfacher, den Code zu lesen und auszuarbeiten, insbesondere, wenn der Code-Fluss ziemlich stark springt .

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

Schließlich muss man bedenken, dass Kommentare als Code ebenfalls Teil des Systems sind. 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 diese schlechter als nutzlos sind, wenn sie falsch sind.

1
BlackWasp

Unabhängig davon, ob rein selbstdokumentierender Code erreichbar ist, gibt es einige Dinge, die man sowieso tun sollte:

  • Niemals Code haben, der "überraschend" ist. Dh Verwenden Sie keine dummen Makros, um Dinge neu zu definieren. Missbrauchen Sie nicht die Überladung von Operatoren und versuchen Sie nicht, diesbezüglich klug zu sein.
  • Code am richtigen Punkt aufteilen. Verwenden Sie geeignete Abstraktionen. Verwenden Sie eine Abstraktion mit einem Eigennamen, anstatt einen fortlaufenden Puffer (einen Puffer mit fester Länge, mit zwei Zeigern, die Elemente an einem Ende hinzufügen und am anderen entfernen) einzufügen.
  • Halten Sie die Funktionskomplexität gering. Wenn es zu lang oder zu komplex wird, versuchen Sie, es in andere Funktionen aufzuteilen.

Fügen Sie bei der Implementierung spezifischer komplexer Algorithmen eine Dokumentation (oder einen Link zu) hinzu, die den Algorithmus beschreibt. In diesem Fall sollten Sie jedoch besonders sorgfältig vorgehen, um unnötige Komplexität zu beseitigen und die Lesbarkeit zu erhöhen, da es zu leicht ist, Fehler zu machen.

1
Paul de Vrieze

Ich denke, es ist eine Frage der richtigen Menge an Dokumentation und nicht aller oder keiner. Wenn die Parameter einer Funktion gut benannt sind, müssen Sie oft nicht genau sagen, was sie sind, z. char * Kundenname ist ziemlich offensichtlich. Wenn Sie Assert-Wertebereiche für Parameter verwenden, müssen Sie diese Bereiche auch nicht dokumentieren. IMO sollte die Dokumentation alles abdecken, was nicht offensichtlich ist und daher eine Erklärung benötigt, und der meiste Code benötigt eine Dokumentation. Persönlich würde ich eher ein anschauliches Beispiel dafür sehen, wie eine bestimmte Funktion funktioniert, als in den meisten Fällen eine beschreibende Dokumentation.

Dokumentation um der Dokumentation willen kann Zeitverschwendung sein, da die Dokumentation gewartet werden muss, um mit der Codebasis auf dem neuesten Stand zu sein. Wenn niemand vom Lesen profitiert, produziere es nicht.

1
SmacL

Ich benutze immer System.out, um zu erklären, was Code macht. Auf diese Weise können Sie es ausdrucken und zu Hause lesen: p

1
user28791

Ich würde das umdrehen.

Fragen Sie sich, was Sie in seinem Code nicht verstehen, und bitten Sie ihn, diese zu dokumentieren. Und vielleicht könnten Sie uns auch etwas erzählen.

1
iny

Ich habe einmal mit einem Mann zusammengearbeitet, der im Begriff war, eine Finanzsuite an eine große Firma zu verkaufen. Sie bestanden darauf, dass er den Quellcode dokumentierte, für den er eine 30-seitige Assembler-Routine erstellte, und sagten: "Es ist dokumentiert, sieh mal" - dann blätterte er auf Seite 13 und es gab einen Kommentar "Stoßzähler um eins". Tolles Produkt, toller Implementierer, aber ...

Wie auch immer, meiner Meinung nach dienen die wichtigen Kommentare oben dazu, den Kontext zu bestimmen. Dieses Snippet wurde als selbstdokumentiert angegeben:

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

Aber ich für meinen Teil brauche einen Kontext, um ihn vollständig zu verstehen.

1
jsfain

Es wurde darauf hingewiesen, dass Kommentare die Absicht erfassen sollten, aber ich würde noch ein wenig weiter gehen.

Ich denke, für jede Klasse von Problemen gibt es ein ideales (oder fast so) Vokabular und eine ideale Syntax, um sie zu beschreiben, und Sie können es sehen, wenn Sie nur die Person fragen, die solche Probleme hat, um sie zu beschreiben (vorausgesetzt, diese Person kann klar denken). .

Wenn dieses Vokabular und diese Syntax leicht (durch Definieren von Klassen, Methoden usw.) auf Code in einer Computersprache abgebildet werden können, kann dieser Code selbstdokumentierend sein. Außerdem wurde IMO, eine domänenspezifische Sprache, erstellt. (Und das ist meine grobe Definition von "deklarativ".)

Wenn dieses Ideal nicht erfüllt ist und das Problem nicht so direkt auf den Computercode abgebildet wird, benötigen Sie etwas, um die beiden miteinander zu verbinden. IMO, das ist der Zweck von Kommentaren.

Wenn sich das Problem ändert, können Sie auf diese Weise die entsprechenden Teile des Codes finden, die geändert werden sollen.

EDIT: Ich bin übrigens nicht für die OOP) -Methode, bei der jedes Substantiv zu einer Klasse und jedes Verb zu einer Methode wird. Ich habe genug aufgebaute Bloatware gesehen auf diese Weise.

1
Mike Dunlavey

Hier sind meine besten Antworten auf Ihre Fragen.

Selbstdokumentierender Code ist Code, der klar mit Klassen-, Methoden-, Funktions- und Variablennamen geschrieben ist, damit seine Absicht und Funktion leicht verstanden werden. Wenn es gut gemacht ist, ist es die Dokumentation.

Es kann Code ersetzen, der gut kommentiert und dokumentiert ist, aber ich habe ihn selten gesehen. Zu oft glauben Programmierer, dass sie gut genug sind, um dies zu tun, aber der beste Weg, sie niederzuschlagen, besteht darin, Fragen zu stellen. Wenn sie zu viel erklären müssen, war ihr Code nicht klar genug. Sie sollten den Code nicht lesen müssen, um zu wissen, was er tut.

Es kann Situationen geben, in denen es besser ist. Wenn der Code klein und einfach ist, können Sie durch Hinzufügen von Dokumentation Unordnung schaffen.

Code, der einen Algorithmus enthält, sollte Kommentare enthalten. In den meisten Fällen können sich selbst die ursprünglichen Programmierer nicht daran erinnern, was zum Teufel sie vor ein paar Monaten gedacht haben, als sie eine lange Funktion geschrieben haben.

1
wandercoder

Dies ist eine ausgezeichnete Frage. Es geht auf die erste Programmiersprache zurück, die Kommentare erlaubt hat, da bin ich mir sicher. Der Code sollte auf jeden Fall so selbstdokumentierend wie möglich sein. Kommentare, die auf das Offensichtliche hinweisen, sollten gestrichen werden. Kommentare, die das Verständnis der Absicht, des Zwecks und der Verwendung einer bestimmten Methode oder eines bestimmten Codeabschnitts erleichtern, können für diejenigen von uns von unschätzbarem Wert sein, die mit der betreffenden Sprache oder dem betreffenden Code möglicherweise weniger vertraut sind. Ein gutes Beispiel sind strukturierte Kommentare, mit denen API-Dokumentationen erstellt werden können. Kommentieren Sie einfach keine IF-Anweisung, die prüft, ob ein Kontrollkästchen aktiviert ist, und teilen Sie mir mit, dass Sie prüfen, ob das Kontrollkästchen aktiviert ist. Das Offensichtliche in einem Kommentar wiederzugeben, ist der schlimmste Tastenanschlag in unserem Universum.

//For example, the above text deals with what is a useful comment
1
Tyler Jensen

Sehr gemischte Eingänge hier scheint es :)

Ich benutze den Pseudocode-Programmierprozess für Neuentwicklungen, wodurch sich mein Code praktisch selbst dokumentiert. Ich beginne erst mit dem Schreiben von Pseudocode, wenn ich neuen Code schreibe, und erweitere ihn dann. Ich sage nicht, dass dies eine bewährte Methode oder etwas Ähnliches ist. Ich möchte nur eine Technik hervorheben, die ich nützlich finde, wenn Sie wissen, dass Sie eine Menge Dokumentation für Ihren Code benötigen, wenn er an Dritte, Prüfer usw. geht hebt gelegentlich Probleme für mich hervor, bevor ich überhaupt eine Codezeile geschrieben habe.

' check database is available
  ' if it is then allow the procedure
  ' if it isnt roll back and tidy up 
' move onto something else

wird;

' check database is available
  if checkDBStateResult(currentDB) = Open then 
     ' if it is then allow the procedure
          proc.Ok = True 
  else
     ' if it isnt roll back
          proc.Ok = False
          CleanUp()
  end if
1
CaRDiaK

Selbstdokumentierender Code ist Albernheit. Jeder, der seinen Code nach Wochen, Monaten oder nach Luft schnappen Jahren erneut aufrufen musste, weiß das (oder in meinem Fall nach Tagen). (Vielleicht ist der Typ, der für diese Idee wirbt, noch nass hinter den Ohren!?!?!)

Verwenden Sie aussagekräftige, beschreibende Datennamen, faktorisieren Sie Ihren Code intelligent und hinterlassen Sie Hinweise, warum Sie genau das getan haben, was Sie getan haben, und Sie werden ein reichhaltigeres und erfüllteres Leben führen.

Obwohl ... Ich habe einmal ein Zitat gelesen, das Bill Gates zugeschrieben wurde: "Der Code IS the documentation."

Stelle dir das vor.

1
Chuck Wright

Selbstdokumentierender Code ist einfach zu verstehender Code. Variablennamen sind ein langer Weg, um Code selbst zu dokumentieren, aber ich finde, die beste Taktik besteht darin, jede komplizierte Logik in winzige kleine Stücke zu zerlegen und diese Informationen in separate Methoden mit ausführlichen und informativen Namen umzuwandeln. Dann werden Ihre komplizierten Methoden einfach zu einer Liste der auszuführenden Schritte. Die winzigen privaten Hilfsmethoden werden dann durch ihren eigenen Methodennamen ausreichend dokumentiert und die komplizierten Methoden werden als eine Folge von auszuführenden abstrakten Schritten dokumentiert. In der Praxis kann diese Strategie nicht immer perfekt angewendet werden, sodass Kommentare immer noch sehr nützlich sind. Außerdem sollten Sie niemals ein Tool ganz aufgeben, mit dem Sie Code schreiben können, der einfacher zu verstehen ist.

1

Selbstdokumentierter Code ist Code, der so klar ist, dass ein Kommentar nicht erforderlich wäre. Ich gebe ein kleines Beispiel:

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

Der Kommentar ist ziemlich nutzlos, weil der Code klar ist. Dokumentation ist eine gute Praxis, aber zusätzliche Dokumentation kann dem Code unnötiges Rauschen hinzufügen. Was Ihr Kollege wissen muss, ist, dass nicht jeder den Code des anderen lesen und alle Details bestätigen kann.

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

Das letzte Snippet wäre ohne den Kommentar besonders schwer zu entschlüsseln. Sie können sich andere Beispiele vorstellen, die ausgefallener sind.

0
Miguel Ping