Was ist selbsterklärend Code und kann es gut Code dokumentiert ersetzen? [geschlossen]

https://stackoverflow.com/questions/209015

03-07-2019
|

Frage

Ich habe einen Kollegen, der darauf besteht, dass sein Code Kommentare nicht braucht, ist es „selbstdokumentiere.“

Ich habe seinen Code überprüft, und während es klarer als Code, den ich gesehen habe, andere produzieren, Ich bin nicht einverstanden, dass nach wie vor selbsterklärend Code so vollständig und nützlich als auch kommentiert und dokumentiert Code.

Helfen Sie mir verstehen sein Sicht.

Was selbstdokumentierenden Code ist
Kann es wirklich ersetzen gut kommentiert und dokumentiert Code
Gibt es Situationen, in denen es besser als gut dokumentiert und kommentierten Code
Gibt es Beispiele, wo Code kann unmöglich ohne Kommentare selbsterklärend sein

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

Dies ist nicht dazu gedacht, ein Argument zu sein - bitte nicht bringen Gründe, warum gut kommentiert und dokumentierte Code ist mit hohen Priorität - es gibt dieses viele Ressourcen zeigen, aber sie sind nicht überzeugend zu meinem Peer. Ich glaube, ich brauche, um mehr vollständig seine Perspektive zu verstehen ihn vom Gegenteil zu überzeugen. Starten Sie eine neue Frage, wenn Sie müssen, aber nicht hier streiten.

Wow, schnelle Antwort! Bitte lesen Sie alle bestehenden Antworten und Kommentaren versehen Antworten anstatt neue Antworten hinzufügen, es sei denn Ihre Antwort wirklich wesentlich von jeder anderen Antwort ist hier drin.

Auch diejenigen, die sich nicht selbst dokumentiere Code streiten werden -Das ist in erster Linie um mir zu helfen, die Perspektive zu verstehen (dh positive Aspekte) der Selbst dokumentieren Code Evangelisten. Ich erwarte, dass andere Sie downvote, wenn Sie nicht auf Thema bleiben.

Lösung

Meiner Meinung nach, sollte jeder Code selbsterklärend sein. In gut, selbst dokumentierte Code, müssen Sie nicht jede einzelne Zeile erklären, weil jede Kennung (Variable, Methode, Klasse) hat einen klaren semantischen Namen. mehr Kommentare als nötig zu haben, macht tatsächlich schwieriger ist es (!), um den Code zu lesen, so dass, wenn Ihr Kollege

schreibt Dokumentation Kommentare (Doxygen, JavaDoc, XML-Kommentare etc.) für jede Klasse, Mitglied, Art und Verfahren und
Kommentare eindeutig alle Teile des Codes, die nicht selbstdokumentierend und
schreibt, dass ein Kommentar für jeden Block von Code, der die Absicht erklärt, oder das, was der Code tut auf einer höheren Abstraktionsebene (dh finden Sie alle Dateien, die größer als 10 MB statt Schleife durch alle Dateien in einem Verzeichnis, Test, wenn die Dateigröße größer als 10 MB, yield return wenn true )

sein Code und Dokumentation ist in Ordnung, meiner Meinung nach. Beachten Sie, dass selbst dokumentierte Code tut nicht bedeutet, dass es keine Kommentare, sondern nur, dass es keine unnötigen Kommentare sein. Die Sache ist jedoch, dass der Code durch das Lesen (einschließlich Kommentare und Dokumentation Kommentare) sollten sofort Verständnis ergeben, was der Code tut und warum. Wenn der „selbsterklärend“ Code länger dauert als kommentierten Code zu verstehen, ist es nicht wirklich selbsterklärend.

Andere Tipps

Nun, da diese über Kommentare und Code ist, wollen wir uns einige tatsächliche Code aussehen. Vergleichen Sie diese typischen Code:

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

Zu diesem selbsterklärend Code, der zeigt, was getan wird:

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

Und dann diesen dokumentierten Code, der besser erklärt Warum es getan 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 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 Kommentierung Stil:

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, Kommentare verwendet werden, wenn Variablen deskriptiv statt benannt worden sein, und die Ergebnisse einer Operation zusammengefasst werden, wenn wir klar sehen können, was die Operation. Ich würde jeden Tag die Selbst dokumentiert zweites Beispiel dazu bevorzugen, und vielleicht ist das, was Ihr Freund spricht, wenn er sagt, selbst dokumentierte Code.

Ich würde sagen, dass es auf dem Kontext abhängt, was Sie tun. Für mich ist das selbst dokumentierte Code wahrscheinlich ausreichend in diesem Fall, aber ein Kommentar detailliert die Methodik hinter dem, was hinter getan wird (in diesem Beispiel ist die Gleichung) ist ebenfalls nützlich.

Der Code selbst wird immer gehen die meisten up-to-date sein Erklärung dessen, was Ihr Code tut, aber meiner Meinung nach für sie es ist sehr schwer zu erklären Absicht , das ist die wichtigste Aspekt der Kommentare. Wenn es richtig geschrieben wird, wissen wir bereits, was der Code tut, wir müssen nur wissen, , warum auf der Erde es tut!

Jemand hat einmal gesagt,

1) schreiben Nur Kommentare zu Code, der schwer zu verstehen ist.
2) Versuchen Sie nicht, den Code zu schreiben, die schwer zu verstehen.

Die Idee hinter „selbsterklärend“ Code ist, dass die eigentliche Programmlogik im Code trivialen klar genug ist, um jedermann zu lesen, den Code zu erklären, nicht nur, was der Code tut, aber warum es es tut.

Meiner Meinung nach ist die Idee des wahren selbsterklärend Code ist ein Mythos. Der Code kann Ihnen sagen, die Logik hinter dem, was geschieht, aber es kann nicht erklären, warum es eine gewisse Art und Weise getan wird, vor allem, wenn es mehr als ein Weg, um ein Problem zu lösen. Schon aus diesem Grunde kann es nie ersetzen gut kommentiert Code.

Ich denke, dass es relevant ist die Frage, ob eine bestimmte Codezeile selbsterklärend ist, aber am Ende, wenn Sie die Struktur und Funktion von einer Scheibe Code nicht verstehen, dann die meiste Zeit Kommentare werden nicht helfen werden. Nehmen wir zum Beispiel, amdfan der Scheibe „korrekt kommentierte:“ Code:

/* 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 die folgende ist ebenso informativ in den meisten modernen Softwaresystemen und erkennt ausdrücklich an, dass eine Newtonsche Berechnung unter Verwendung eine Wahl, die einige andere physikalische Paradigma besser geeignet geändert werden können, sollte:

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

In meiner persönlichen Erfahrung, gibt es sehr wenige „normale“ Codierung Situationen, in denen Sie absolut Kommentare müssen. Wie oft beenden Sie Ihren eigenen Algorithmus Aufrollen, zum Beispiel? Im Grunde genommen alles andere ist eine Frage der Strukturierung Ihres Systems, so dass ein Programmierer die Strukturen in Gebrauch und die Entscheidungen nachvollziehen kann, die das System trieb diese speziellen Strukturen zu verwenden.

ich vergessen, wo ich das bekam aus, aber:

Jeder Kommentar in einem Programm ist wie eine Entschuldigung für den Leser. „Es tut mir leid, dass mein Code so undurchsichtig ist, dass Sie es nicht an ihn, indem man verstehen können“. Wir müssen einfach akzeptieren, dass wir nicht perfekt sind, aber danach streben, perfekt zu sein, und gehen Sie nach rechts auf entschuldigend, wenn wir müssen.

Selbst Dokumentieren Code ist ein gutes Beispiel für "DRY" (Do not Repeat Yourself). Geben Sie keine Informationen in den Kommentaren duplizieren, die ist oder sein kann, in den Code selbst.

Anstatt erklären, was eine Variable für verwendet wird, benennen Sie die Variable.

Anstatt zu erklären, was ein kurzer Code-Snippet ist, es in ein Verfahren extrahieren und einen beschreibenden Namen geben (vielleicht eine verkürzte Version Ihres Kommentars Text).

Anstatt zu erklären, was eine komplizierte Prüfung nicht, extrahiert, dass in ein Verfahren zu und gibt ihm einen guten Namen.

Etc.

Danach Sie mit dem Code am Ende, die nicht so viel Erläuterung bedarf, es erklärt sich von selbst, so dass Sie die Kommentare löschen sollte, die lediglich im Code wiederholen.

Das bedeutet nicht, dass Sie überhaupt keine Kommentare haben, gibt es einige Informationen, die Sie nicht in den Code wie zB Informationen über Intent (das „Warum“) setzen können. Im Idealfall ergänzen Sie den Code und die Kommentare voneinander jeweils und jede Menge Erklärungswert, ohne die Information in den anderen zu duplizieren.

selbsterklärend Code ist eine gute Praxis, und wenn sie richtig die Bedeutung des Codes erfolgen kann, ohne das Lesen zu viele Kommentare leicht vermitteln. insbesondere in Situationen, in denen ist die Domain auch von jedem im Team verstanden.

Having said that, Kommentare für Neulinge sehr hilfreich sein können, oder für Tester oder Dokumentation zu generieren / Hilfe-Dateien.

selbsterklärend Code + notwendig Kommentare werden einen langen Weg in Richtung zum Helfen Menschen in Teams gehen.

Zunächst einmal ist es gut zu hören, dass Code Ihres Kollegen in der Tat ist klarer als anderer Code, den Sie gesehen haben. Es bedeutet, dass er wahrscheinlich nicht, weil sie zu faul „selbsterklärend“ als Vorwand, mit seinem Code zu kommentieren.

Selbst Dokumentieren Code ist Code, der nicht Freitextkommentare für einen informierten Leser benötigen, um zu verstehen, was es tut. Zum Beispiel dieses Stück Code ist selbsterklärend:

print "Hello, World!"

und so ist dies:

factorial n = product [1..n]

und so ist dies:

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)

Nun, diese Idee eines „informierten Leser“ ist sehr subjektiv und situationsabhängig. Wenn Sie oder jemand andere Probleme haben folgenden Code Ihren Kollegen, dann würde er auch tun, um seine Vorstellung von einem informierten Leser neu zu bewerten. Ein gewisser Grad an Vertrautheit mit der Sprache und Bibliotheken verwendet wurde, muss davon ausgegangen werden, um Code selbsterklärend zu nennen.

Das beste Argument habe ich für das Schreiben „selbsterklärend Code“ zu sehen ist, dass es das Problem des Freitextkommentar vermeidet mit dem Code nicht einverstanden, wie geschrieben steht. Die beste Kritik ist, dass während Code beschreibt was und wie es selbst tut, kann es nicht erklären Warum wird etwas auf eine bestimmte Weise getan .

Um:

Selbst dokumentiert Code ist Code, der seine Absicht, den Leser klar zum Ausdruck bringt.
Nicht ganz. Kommentare sind immer hilfreich für die Kommentierung Warum eine bestimmte Strategie gewählt wurde. Doch die Kommentare erklären was ein Abschnitt des Codes wird, sind dabei von Code, die nicht hinreichend selbsterklärend ist und könnte etwas Refactoring verwenden ..
Kommentare liegen und veralten. Code ~~sagt immer~~ ist wahrscheinlicher, die Wahrheit zu sagen.
Ich habe noch nie einen Fall, wo die was Code gesehen nicht ausreichend ohne Kommentar deutlich gemacht werden könnte; aber wie ich bereits sagte, ist es manchmal notwendig / hilfreich Kommentar zu dem Warum enthalten.

Es ist wichtig zu beachten Sie jedoch, dass wirklich selbstdokumentiere Code viel Selbst- und Team Disziplin nimmt. Sie müssen lernen, mehr deklarativ zu programmieren, und Sie haben sehr bescheiden sein und „clever“ Code für Code zu vermeiden, die so offensichtlich ist, dass es scheint, wie jemand es geschrieben haben könnte.

Zum einen betrachten Sie 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 Zeilen Kommentare pro 3 Zeilen Code. Noch schlimmer ist - die Kommentare hinzufügen nicht alles, was Sie nicht durch das Lesen des Codes sehen. Wenn Sie 10 Methoden wie diese haben, können Sie sich ‚Kommentar Blindheit‘ und nicht das ein Verfahren fest, die aus dem 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;
 }

Noch für trivialen Code, den ich lieber keine Kommentare zu müssen. Die Absicht und die gesamte Organisation außerhalb des Codes in einem separaten Dokument besser erläutert wird.

Wenn Sie einen „selbsterklärend Code“ gelesen, sehen Sie, was es tut, aber man kann nicht immer erraten, warum es in dieser bestimmten Art und Weise tut.

Es gibt Unmengen von nicht-Programmierung Einschränkungen wie Business-Logik, Sicherheit, Benutzeranforderungen etc.

Wenn Sie Wartung zu tun, diejenigen backgorund Informationen sehr wichtig geworden.

Nur meine Prise Salz ...

Eine Sache, die Sie wünschen können Sie mit Ihrem Kollegen darauf hinweisen, ist, dass egal wie selbst dokumentiert seinen Code ist, wenn andere alternative Ansätze wurden geprüft und verworfen, dass die Informationen verloren gehen, wenn er den Code mit dieser Information kommentiert. Manchmal ist es ebenso wichtig zu wissen, dass eine Alternative in Betracht gezogen wurde und warum es wurde beschlossen, gegen und Code Kommentare sind höchstwahrscheinlich im Laufe der Zeit zu überleben.

Haben Sie schon von Donald Knuth "WEB" Projekt hörte seine Literate Programming Konzept zu implementieren? Es ist mehr als selbsterklärend Code; es ist eher wie Dokumentation, die als Code kompiliert und ausgeführt werden kann. Ich weiß nicht, wie viel es aber heute verwendet wird.

Der Unterschied zwischen "was" und "wie".

Sie sollten dokumentieren, "was" eine Routine der Fall ist.
Sie sollten nicht dokumentieren „wie“ es tut, es sei denn, Sonderfälle (beispielsweise auf einen spezifischen Algorithmus Papier beziehen). Das sollte selbst dokumentiert werden.

In einem Unternehmen, in dem ich einen der Programmierer gearbeitet hatte die an der Spitze ihres Monitors stecken folgen.

„Dokumentieren Sie Ihre Code wie die Person, die es unterhält ein Mörderischer Maniac ist, der weiß, wo Sie leben.“

Der Standpunkt, dass Code selbstdokumentiere ist macht mich verrückt. Eine bestimmte Codezeile oder ein Sub-Algorithmus kann in der Tat selbstdokumentierenden, aber es ist Zweck in der größeren picutre einfach ist es nicht.

Ich habe so frustriert mit diesem einen Monat oder zwei Jahren schrieb ich einen ganzen Blog-Eintrag beschreibt meiner Sicht. Beitrag hier .

selbsterklärend Code verwendet normalerweise Variablennamen, die genau dem entsprechen, was der Code tut, so dass es leicht zu verstehen ist, was auf

wird

Allerdings ist eine solche „selbsterklärend Code“ wird nie Kommentare ersetzen. Manchmal ist der Code einfach zu komplex und selbsterklärend Code ist nicht genug, vor allem in der Art und Weise der Wartbarkeit.

Ich hatte einmal einen Professor, der einen überzeugten Anhänger dieser Theorie war In der Tat ist das Beste, was ich ihn sagen, erinnern „Kommentare sind für Weichlinge“
Es dauerte uns alle überrascht auf den ersten, aber es macht Sinn.
Allerdings ist die Situation, dass, obwohl Sie in der Lage sein kann, zu verstehen, was im Code vorgeht, aber jemand, der weniger erfahren ist, dass Sie hinter sich und nicht verstehen kann kommen, was los ist. Dies ist, wenn Kommentare an Bedeutung. Ich weiß, viele Male, dass wir nicht glauben, sie sind wichtig, aber es gibt nur sehr wenige Fälle, in denen Kommentare unnötig sind.

Ich bin überrascht, dass niemand über „ Literate Programming “ gebracht hat, eine Technik entwickelt, 1981 von Donald E. Knuth von TeX und "The Art of Computer Programming" Ruhm.

Die Prämisse ist einfach: da der Code von einem Menschen verstanden werden muss und Kommentare entfernt vom Compiler einfach geworfen, warum jeder nicht gibt das, was sie brauchen - eine vollständige Textbeschreibung der Absicht des Codes, befreit von Programmiersprache Anforderungen, für die menschlichen Leser und reinen Code für den Compiler.

Literate Programming Tools tun dies, indem Sie spezielle Markup für ein Dokument geben, das die Tools mitteilen, welche Teil Quelle sein sollte und was ist Text. Das Programm später zerreißt die Quellcode Teile aus dem Dokument und fügt eine Code-Datei.

Ich fand ein Beispiel auf dem Netz davon: http://moonflare.com/code /select/select.nw oder die HTML-Version http://moonflare.com/ Code / select / select.html

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

Das Selbst dokumentieren Code, komplett mit Argumentation und alle. Auch macht ein schönes Dokument, Alles andere ist nur gut geschrieben Kommentare ist: -)

Meine Ansicht ist in diesem Beitrag geschrieben:

die einzige Spitze dokumentieren Sie den Code.

Auszug:

Statt eine Menge Kommentare zu schreiben   zu erklären, die subtilen Verhaltensweisen   Ihr Programm, umstrukturieren, warum nicht Ihre   Logik, so dass sie selbstverständlich?   Anstatt zu dokumentieren, was eine Methode   tut, warum nicht wählen einen eindeutigen Namen   für diese Methode? Statt Tagging   Ihr Code unfertig, um anzuzeigen,   warum nicht nur ein Wurf   (NotImplementedException)? Anstatt von   kümmern, ob Ihre Kommentare Ton   höflich genug, um Ihren Chef, Ihre   Kollegen oder jemand den Code zu lesen,   warum nicht nur stoppen, indem nicht besorgniserregend   sie überhaupt schreiben?

Je klarer Ihr Code ist, desto leichter   ist es zu halten, um sie zu erweitern, zu   arbeiten sie auf zukünftige Ausgaben. Das   weniger ordorous ist der Code, desto weniger   braucht es dazu zu äußern. Je mehr   Kommentare, desto höher ist die   maintanence Kosten.

Ich mag eine weitere Perspektive auf die vielen gültigen Antworten bieten:

Was ist Quellcode? Was ist eine Programmiersprache?

Die Maschinen müssen Quellcode nicht. Sie sind glücklich laufen Montage. Programmiersprachen sind zu unserem Nutzen. Wir wollen keine Montage schreiben. Wir müssen verstehen, was wir schreiben. Die Programmierung erfolgt über das Schreiben von Code.

Wenn Sie in der Lage sein, zu lesen, was Sie schreiben?

Der Quellcode wird in der menschlichen Sprache nicht geschrieben. Es wird versucht (zB Fortran), aber es ist nicht ganz erfolgreich.

Der Quellcode kann nicht Mehrdeutigkeit hat. Deshalb müssen wir mehr Struktur in ihr, als wir mit dem Text zu tun. Text funktioniert nur mit Rahmen, die wir für selbstverständlich halten, wenn wir Text verwenden. Kontext in Quellcode ist immer Explisit. Denken Sie "verwenden" in C #.

Die meisten Programmiersprachen haben Redundanz, so dass der Compiler kann uns fangen, wenn wir nicht kohärent sind. Andere Sprachen verwenden mehr Inferenz und versuchen, diese Redundanz zu vermeiden.

Geben Sie Namen, Methode Namen und Variablennamen sind nicht von den Computern benötigt. Sie werden von uns verwendet, für die Referenzierung. Der Compiler versteht nicht, Semantik, das ist für uns zu nutzen.

Programmiersprachen sind eine sprachliche Brücke zwischen Mensch und Maschine. Es muss beschreibbar sein für uns und lesbar für sie. Secondary Forderungen sind, dass es für uns lesbar sein sollte. Wenn wir Semantik gut sind, wo erlaubt und gut darin, den Code zu strukturieren, sollte Quellcode einfach sein, auch für uns zu lesen. Der beste Code nicht Kommentare müssen.

Aber Komplexität lauert in jedem Projekt, müssen Sie immer entscheiden, wo die Komplexität zu bringen, und die Kamele zu schlucken. Das sind die Orte, Kommentare zu verwenden.

Selbst Dokumentieren Code ist eine einfache Opt-out des Problems, dass im Laufe der Zeit-Code, Kommentar und Dokumentation abweichen. Und es ist ein Disziplinierungsfaktor klar, Code zu schreiben (wenn Sie so streng sind auf sich selbst).

Für mich ist dies die Regeln, die ich versuche zu folgen:

-Code sollte so einfach und klar sein, lesen wie möglich.
Kommentare sollten begründen Design-Entscheidungen Ich habe, wie: warum kann ich diesen Algorithmus verwenden oder Einschränkungen der Code hat, wie: tut wenn nicht ... (dies sollte sein in einem Vertrag / Behauptung behandelt in der Code) (in der Regel innerhalb der Funktion / Prozedur).
Die Dokumentation sollte Verwendungsliste (Aufruf converntions), Seite Effekte, mögliche Rückgabewerte. Es kann aus dem Code extrahiert werden unter Verwendung von Tools wie jdoc oder xmlDoc. Es Daher ist in der Regel außerhalb der Funktion / Prozedur, aber in der Nähe des Code beschreibt.

Das bedeutet, dass alle drei mittels Code zu dokumentieren leben dicht beieinander und sind daher eher geändert werden, wenn die Code-Änderungen, aber nicht überlappen, was sie ausdrücken.

Das eigentliche Problem mit dem sogenannten selbsterklärend Code ist, dass es vermittelt, was es tatsächlich der Fall ist. Während einige Kommentare der Code besser (zum Beispiel Algorithmen Schritte, etc.) helfen jemand es verstehen kann zu einem gewissen Grad redundant und ich bezweifle, dass Sie Ihre Peer überzeugen würde.

Doch was in der Dokumentation wirklich wichtig ist, ist das Zeug, das nicht unmittelbar ersichtlich ist aus dem Code: zugrundeliegende Absicht, Annahmen, Auswirkungen, Einschränkungen usw.

Die Möglichkeit, zu bestimmen, dass ein Code tut X von einem schnellen Blick ist viel einfacher als in der Lage zu sein, um zu bestimmen, dass ein Code nicht Y. tut Er hat Y zu dokumentieren ...

Sie könnten ihm ein Beispiel für einen Code zeigen, der gut aussieht, ist offensichtlich, aber deckt nicht tatsächlich alle Basen des Eingangs, zum Beispiel, und sehen, ob er es findet.

Ich denke, dass selbsterklärend Code ein guter Ersatz für Kommentierung ist. Wenn Sie Kommentare erfordern, zu erklären, wie oder warum Code ist so, wie es ist, dann haben Sie eine Funktion oder Variablennamen, die geändert werden sollten erklärend. Es kann als nach unten zu dem Codierer sein, ob er den Fehlbetrag mit einem Kommentar bilden werden oder einige Variablen und Funktionen und Refaktorierungscode Umbenennung though.

Es kann Ihre Dokumentation aber nicht wirklich ersetzen, weil Dokumentation ist, was Sie andere geben, zu erklären, wie das System zu verwenden, anstatt, wie es Dinge tut.

Edit: Ich (und wahrscheinlich auch alle anderen) sollte wahrscheinlich die Bestimmung haben, die eine digitale Signalverarbeitung (DSP) App sehr gut kommentiert werden sollte. Das ist vor allem, weil DSP-Anwendungen im Wesentlichen 2 für Schleifen mit Arrays von Werten gespeist sind und fügt / vervielfacht / etc die Werte ... das Programm die Werte in einem der Felder ändern sich ändern ... ein paar Kommentare muss zu sagen, was Sie sind in diesem Fall zu tun;)

Wenn mathematischen Code zu schreiben, habe ich manchmal fand es nützlich lange, Essay artige Kommentare schreiben zu können, erklärt die Mathematik, die Darstellungsmittel der Code verwendet, und wie alles zusammen passt. Wir sind Hunderte von Zeilen der Dokumentation zu sprechen, hier.

Ich versuche, meinen Code als selbsterklärend wie möglich zu machen, aber wenn ich zurückkomme nach ein paar Monaten, daran zu arbeiten, ich brauche wirklich die Erklärung zu lesen, aus machen einen Hash aus ihm heraus zu halten.

Nun, natürlich ist diese Art von extremer Maßnahme ist für die meisten Fälle nicht erforderlich. Ich denke, die Moral von der Geschichte ist: verschiedene Code unterschiedliche Mengen an Dokumentation erfordert. Einiger Code kann so klar geschrieben, dass es nicht Kommentare braucht - so schreibt es die klar und Kommentare dort nicht verwenden

Aber viele Code brauchen Kommentare Sinn zu machen, so schreibt es so klar wie möglich und dann so viele Kommentare zu verwenden, wie es braucht ...

Ich würde behaupten - wie viele von Ihnen tun - das ist wirklich selbstdokumentiere zu sein, muss Code in irgendeiner Form Absicht zeigen. Aber ich bin überrascht, niemand BDD noch erwähnt - Verhalten Driven Development . Ein Teil der Idee ist, dass Sie automatisierte Tests haben (Code) zu erläutern, die Absicht des Codes, die so schwer ist offensichtlich anders zu machen.

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software

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

Der Code, den Sie betrachten wurde automatisch generiert und damit alle Änderungen an dem Code könnte das nächste Mal verprügelt werden das Projekt kompiliert wird,
A weniger als einfache Implementierung wurde für einen Leistungsgewinn (Abrollen eine Schleife, die Schaffung einer Lookup-Tabelle für eine teure Berechnung usw.)

Sein Gehen alle in dem, was die Teamwerte in der jeweiligen Dokumentation zu sein. Ich würde vorschlagen, dass die Dokumentation, warum / Absicht statt, wie wichtig ist und dies nicht immer in selbstdokumentierenden Code erfaßt wird. get / set keine sind diese offensichtlich - aber Berechnung, Retrieval usw. etwas von der, warum sollte ausgedrückt werden.

Auch sich bewusst sein Unterschied in Ihrem Team, wenn Sie aus verschiedenen Nationalitäten comming. Unterschiede in der Diktion in die Benennung von Methoden creap:

BisectionSearch

Binary

BinaryChop

Diese drei Methoden von Entwicklern auf 3 verschiedenen Kontinenten geschult beigetragen tun das Gleiche. Nur wenn wir die Kommentare zu lesen, die den Algorithmus beschrieben konnten wir die Vervielfältigung in unserer Bibliothek identifizieren.

Für mich Code zu lesen, die Kommentare braucht, ist wie Text in der Sprache zu lesen, weiß ich nicht. Ich sehe Anweisung und ich verstehe nicht, was sie tut oder warum - und ich habe die Kommentare zu suchen. Ich lese einen Satz, und ich brauche im Wörterbuch zu schauen, um zu verstehen, was es bedeutet.

Es ist in der Regel leicht, Code zu schreiben, dass die Selbst Dokumente, was es tut. Um Ihnen zu sagen, warum es tut so Kommentare mehr geeignet sind, aber auch hier kann Code besser sein. Wenn Sie Ihr System auf jeder Ebene der Abstraktion zu verstehen, sollten Sie versuchen Sie Code wie

Organisation

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

Wo Methodenname spiegelt Ihre Absicht und Methode Körper erklärt, wie Sie Ihr Ziel erreichen. Sie können sowieso nicht ganzes Buch erzählen in ihrem Titel, so Haupt Abstraktionen des Systems noch dokumentiert werden, als auch komplexe Algorithmen, nicht-triviale Verfahren Verträge und Artefakte.

Wenn der Code, der Ihr Kollege Produk wirklich selbst dokumentiert ist - Glück hat und ihn. Wenn Sie denken, dass Ihre Kollegen Code braucht Kommentare - es braucht. Öffnen Sie einfach die meisten nicht-trivialen Platz darin, lesen Sie es einmal und sehen, ob Sie alles verstanden oder nicht. Wenn der Code selbst dokumentiert ist - dann sollten Sie. Wenn nicht - fragen Sie Ihre Kollegen eine Frage, nachdem er gibt Ihnen eine Antwort fragen, warum diese Antwort nicht vorher in den Kommentaren oder Code dokumentiert wurde. Er kann behaupten, dass Code ist selbst Dokument für eine solche intelligente Person wie ihn, aber er hat trotzdem die anderen Teammitglieder zu respektieren - wenn Sie Ihre Aufgaben Verständnis seines Code erfordern und seinen Code nicht erklären Ihnen alles, was Sie verstehen müssen - es braucht Kommentare.

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow