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

258

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.

Adam Davis
quelle
118
Weißt du was mich wirklich beeindruckt? Sie sind mit dem Kerl nicht einverstanden, aber Sie möchten ihn verstehen, nicht mehr Munition gegen ihn.
Kajaco
14
Als Geschichte eines äußerst entgegengesetzten Falles habe ich eine Mitarbeiterin, die Tonnen von Dokumentation schreibt: In jeder CPP-Datei enthält sie ein Handbuch mit mindestens ein paar Dutzend Seiten zur Implementierung und Verwendung der bereitgestellten Funktionen. Sie schreibt jedoch katastrophal lange und komplizierte Funktionen (Einzelfunktionen mit 8000 Codezeilen), kontraintuitive Bezeichner für Variablen und Funktionen usw. Im Vergleich zu ihr würde ich jemanden nehmen, der sich bemüht, selbstdokumentierenden Code zu schreiben, der auf dem Bildschirm nachlässt Kommentare jeden Tag, vorausgesetzt, sein Code ist gut organisiert mit kleinen Funktionen, die leicht zu verstehen sind.
stinky472
Siehe auch
Calmarius
1
Kurz gesagt, man kann die meisten Kommentare vermeiden, die erklären, wie der Code funktioniert, und den Code in dieser Hinsicht selbstdokumentierend machen. Oft muss jedoch auch erklärt werden, warum der Code so funktioniert, wie er funktioniert, z. B. wenn Sie eine Einschränkung in einer Bibliothek umgehen. Normalerweise benötigen Sie Kommentare, um das Warum zu erklären.
Lutz Prechelt
2
Ich habe mit jemandem gearbeitet, der alles überkommentiert hat, aber normalerweise mit nutzlosen Kommentaren wie i++; // increment i- aber ohne Erklärung, warum i an diesem Punkt in der Funktion erhöht werden sollte.
nnnnnn

Antworten:

177

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.

OregonGhost
quelle
In Übereinstimmung mit dieser Antwort denke ich: memeagora.blogspot.com/2008/11/comments-code-smell.html
Maslow
14
Punkt nr. 3 sollte Teil von Punkt nr sein. 1 IMHO, wenn eine Methode so komplex ist, dass sie hohe Abstraktionskommentare für mehrere Codeblöcke erfordert, sollte jeder dieser Codeblöcke eine neue Methode sein.
Bjarke Freund-Hansen
10
+1 für "bedeutet nicht, dass es keine Kommentare geben sollte", was die Meinung einiger Leute zu sein scheint.
Skurmedel
4
Es ist immer noch nicht erforderlich , Folgendes zu kommentieren: public static Collection <Datei> filesGreaterThan (Dateipfad, int sizeInBytes);
Trylks
6
Eine gute Faustregel für mich ist, dass Kommentare niemals erklären sollten, WAS Code tut, sondern verwendet werden können, um zu erklären, WARUM er es tut. Mit anderen Worten, kommentieren Sie einen Codeblock, um zu erklären, warum er vorhanden ist und nicht wie er funktioniert. Wenn Sie den Block in eine klar benannte Methode zerlegen können, ist das sogar noch besser. Darum geht es bei selbstdokumentierendem Code.
Mel
387

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.

ine
quelle
73
Das ganze Stück sollte eigentlich eine Funktion mit einem beschreibenden Namen haben;)
workmad3
7
Ja, die Funktion DisplacementDueToGravity (int timeInSeconds, float gravitationalAcceleration = 9.81) wäre für mich leichter zu lesen.
Cristián Romo
18
Der einzige Kommentar, den ich hier vermisse, ist: Warum 5 Sekunden?
John Nilsson
3
Eine weitere Abstimmung für den beschreibenden Funktionsnamen. Es gibt nicht die Gleichung selbst, aber ich sehe nicht, dass das benötigt wird.
Loren Pechtel
18
Was sind die Einheiten der Gravitationskraft? Es gibt Grenzen, wie viel Sie einem Variablennamen hinzufügen können. Irgendwann müssen Sie erklären, was Sie versuchen zu tun . Oft ist dies nicht offensichtlich , weshalb Sie Code kommentieren müssen. Es ist völliger Unsinn zu sagen Code selbstdokumentierend ist, ist es nur selbst beschreibend .
Nick
172

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!

andygeers
quelle
Einverstanden. Obwohl gelegentlich sogar der beste Code die endgültige Auswirkung verbergen kann, wird dies durch Beantwortung des Warum in Kommentaren behandelt. Wie in "Warum haben Sie diese 5 Variablen gerade auf diese Weise geändert?"
Sam Erwin
Mein 2 Cent: Ist der Fall [Einheit, Spezifikation, Verhalten] nicht eine Antwort auf "Warum um alles in der Welt"? Dann könnten Sie den Testfall lesen und sollten die Absicht erhalten, warum.
Jonke
2
Ich denke, diese können das allgemeine Warum beantworten, aber sie erklären nicht Dinge wie: "Ich fülle diese Struktur so viele Bytes auf, damit sie bei der Übertragung auf eine dunkle Plattform richtig ausgerichtet bleibt." Für diese sind Codekommentare der beste Weg, um institutionelles Wissen zu bewahren.
Tsellon
Und daher sollten Sie kommentieren, wo die Absicht angesichts des Codes selbst nicht eindeutig ist.
Draemon
2
@tsellon, Ihre automatisierte Spezifikation kann Ihnen das sagen, und das Schöne ist, dass der Code den Implementierungscode überprüft. Wenn sich die Implementierung also irgendwie ändert, bricht die Spezifikation. Wie schön ist das Kommentare, die Sie benachrichtigen, wenn der Implementierungscode nicht mehr das tut, was der Kommentar angegeben hat?
Pragmatischer Agilist
96

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.

Loofer
quelle
28
Was für Sie zum Zeitpunkt des Schreibens des Codes trivial zu verstehen scheint, kann für einen anderen später sehr schwer zu verstehen sein, selbst wenn dieser andere in einigen Monaten / Jahren tatsächlich Sie selbst ist.
Anders Sandvig
15
Ich finde Dinge, die ich am Freitag geschrieben habe, oft ziemlich schwer am Montagmorgen zu fummeln :)
Loofer
1
was uns zu "versuchen, keine Kommentare zu schreiben"
mustafabar
37

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 .

Scott Dorman
quelle
1
IMHO Der Block sollte Ihnen das Wie sagen , der Funktionsname sollte Ihnen das Warum sagen . Solange Sie beide zusammen verwenden, vermitteln Sie sowohl Absicht als auch Implementierung .... int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}...
Basic
19

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.

Mike Burton
quelle
2
Wenn Sie mehr Upvotes benötigen, erklärt Ihr Beispiel, warum wir Funktionsnamen verwenden sollten, um die Absicht zu dokumentieren.
Ape-inago
16

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.

EBGreen
quelle
26
Müll. Gute Kommentare im Code haben absolut ihren Platz. Nehmen Sie das Beispiel der Wahl zwischen zwei gleichermaßen korrekten Methoden zur Lösung eines Problems. Ein Kommentar, der erklärt, warum eine Methode der anderen vorgezogen wurde, ist äußerst aussagekräftig, und das kann man nie aus dem Code selbst entnehmen.
Scott Dorman
7
Wenn es zwei EQUALLY CORRECT-Methoden gibt, spielt es dann eine Rolle, warum Sie eine über die andere gewählt haben?
EBGreen
1
Ja, gleich richtig heißt nicht genau dasselbe. Eine Methode kann in bestimmten Situationen schneller sein als eine andere.
Ikke
Wenn Ihre Entscheidungskriterien Geschwindigkeit sind, sind sie nicht GLEICH RICHTIG. Ich sage nicht, dass Kommentare schlecht sind. Nur dass sie erforderlich sind, weil es derzeit keine Programmiersprache gibt, die so eindeutig und eindeutig ist, dass jeder den Code betrachten und sofort die Absicht des Codes erkennen kann.
EBGreen
9
Ich glaube nicht, dass die Leute dieses Zitat so verstehen wie ich. Ich verstehe das so, dass Sie sich bemühen sollten, immer Code zu schreiben, der so klar ist, dass er nicht kommentiert werden muss, sondern dass Sie akzeptieren müssen, dass es ein Ideal ist, das in der Realität niemals funktioniert.
EBGreen
14

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.

Steven Huwig
quelle
14

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.

Keil
quelle
4
Eine Ausnahme: schlechte Programmierer. Ich habe Kommentare gesehen, die besagen, dass Code etwas tut, was er nicht tut. Dann frage ich mich: Soll ich den Code oder den Kommentar korrigieren?
Guge
Sie können Methodennamen in Objective-C nicht schlagen. :)
13

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.

Gulzar Nazim
quelle
9

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.

Avdi
quelle
Ich werde hier einen Nit Pick hinzufügen. Code sagt nicht immer "die Wahrheit". Code kann irreführend sein und seine Absichten sehr leicht verschleiern. Beispielsweise kann eine falsch benannte Variable oder Methode genauso veraltet sein wie ein veralteter Kommentar.
Wedge
Methodennamen können lügen und auch veraltet sein.
Calmarius
7

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

ulm
quelle
6

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.

ddimitrov
quelle
Es mag trivial erscheinen, Getter und Setter zu dokumentieren, aber ich denke, es gibt ein glückliches Medium zwischen einem nutzlosen Kommentar und dem Fehlen eines Kommentars. Bei vielen Javadoc-Kommentaren geht es darum, jemanden zu informieren, der nicht die Neigung hat oder nicht hat, sich den Code in der Methode anzusehen.
James McMahon
6

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.
Stefano Borini
quelle
Entschieden widersprechen. Was eine Routine tut, sollte aus dem Namen ersichtlich sein. Wie es geht, sollte aus dem Implementierungscode ersichtlich sein. Warum die Implementierung so geschrieben wurde, wie sie ist, sollte dokumentiert werden .
Anthony Manning-Franklin
5

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.

Onorio Catenacci
quelle
Du nimmst das in der Regel und schreibst am Ende ein Lehrbuch in deine Codebasis ;-) Ich stimme jedoch nicht offensichtlichen Entscheidungen zu.
ddimitrov
@ddimitrov, das ist eine gute Beobachtung. Aber wie Sie für nicht offensichtliche Entscheidungen sagen (und diese sind normalerweise sowieso diejenigen, die wirklich Dokumentation erfordern), ist dies eine gute Praxis.
Onorio Catenacci
Dokumentieren Sie den Code, der nicht geschrieben wurde! :)
Tony
5

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

JoeOD
quelle
4

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.

Josh Mein
quelle
Dann überarbeiten Sie es, bis es klarer ist. Ich bin fest davon überzeugt, dass es nichts gibt, was mit Code nicht ganz klar gesagt werden kann.
Tigraine
4
Außer warum eine bestimmte Implementierung, ein bestimmter Algorithmus oder eine bestimmte Formel einer anderen gleichermaßen korrekten vorgezogen wurde. Sie können niemals beschreiben, warum eine Auswahl im Code getroffen wurde, sondern nur, was diese Auswahl war.
Scott Dorman
1
@scott: du könntest beide Optionen unter eine größere Klasse stellen und die andere mit einem Kommentar über ... oh warte nicht implementiert.
Ape-inago
4

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

Quantenmechaniker
quelle
Das ist eigentlich das Gegenteil von selbstdokumentierendem Code. Text für den Menschen, Code für die Maschine. Und welche Sprache sollte der Code sein? Montage natürlich. Menschen müssen es nicht lesen, oder? Sie müssen es nur schreiben!
Guge
4

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.

Guge
quelle
3

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.

Ralph M. Rickenbach
quelle
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. 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.

Uri
quelle
3

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

workmad3
quelle
Ein Funktions- oder Variablenname bietet also genügend trivial klaren Kontext, um zu erklären, warum eine Implementierung einer anderen vorgezogen wurde, wenn zwei oder mehr gleichermaßen korrekte Möglichkeiten zur Lösung eines Problems gegeben sind.
Scott Dorman
3

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

kommender Sturm
quelle
3

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 
Torbjørn
quelle
2

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.)
John
quelle
2

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.

MikeJ
quelle
2

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.

Pavel Feldman
quelle
2

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.

sy
quelle
1

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.

Korbin
quelle
1

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.

BlackWasp
quelle