Werden Kommentare als Dokumentationsform betrachtet?

Wenn ich kleine Skripte für mich selbst schreibe, staple ich meinen Code hoch mit Kommentaren (manchmal kommentiere ich mehr als ich codiere). Viele Leute, mit denen ich spreche, sagen, dass ich diese Skripte dokumentieren sollte, obwohl sie persönlich sind, damit ich bereit wäre, wenn ich sie jemals verkaufen würde. Aber sind Kommentare keine Dokumentationsform?

Wäre das nicht:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

als Dokumentation angesehen werden, insbesondere wenn ein Entwickler meinen Code verwendet? Oder wird die Dokumentation als außerhalb des Codes selbst befindlich angesehen?

Kommentare sind definitiv Dokumentation. Bei den meisten Projekten sind Kommentare (leider) die primäre (wenn nicht nur) Form der Projektdokumentation. Aus diesem Grund ist es sehr wichtig, es richtig zu machen. Sie müssen sicherstellen, dass diese Dokumentation trotz Codeänderungen korrekt bleibt. Dies ist ein häufiges Problem bei Kommentaren. Entwickler "schalten" sie häufig aus, wenn sie mit bekanntem Code arbeiten, und vergessen daher, Kommentare zu aktualisieren, um den Code wiederzugeben. Dies kann zu veralteten und irreführenden Kommentaren führen.

Viele Leute schlagen vor, den Code selbst zu dokumentieren. Dies bedeutet, dass Sie anstelle von Kommentaren Ihren Code neu strukturieren, um die Notwendigkeit für sie zu beseitigen. Dies kann die meisten "Was" - und "Wie" -Kommentare beseitigen, hilft aber nicht wirklich bei den "Warum" -Kommentaren. Während dies effektiv funktioniert, um die meisten Kommentare zu entfernen, gibt es immer noch viele Fälle, in denen das Schreiben eines Kommentars die einfachste und effizienteste Möglichkeit ist, einen Code zu dokumentieren.

Sie sind eine Form der Dokumentation, aber denken Sie daran, dass die Dokumentation im Auge des Betrachters liegt.

• Für einige reicht selbstdokumentierender Code aus. Dies setzt jedoch ein Maß an technischen Details als Kunde voraus. Wir sollten vorsichtig denken, dass dies ausreicht, weil unser Ego uns vielleicht sagt "Es ist offensichtlich, was dieser Code tut", aber die Zeit kann das Gegenteil beweisen. Es wird auch davon ausgegangen, dass Sie die Fähigkeiten des Lesers im Voraus kennen.

• Für diejenigen, die sich Quellcode ansehen, aber weniger technisches Fachwissen haben, könnten Kommentare in Ordnung sein. Dies setzt jedoch voraus, dass sich jemand den Quellcode ansieht.

• Wenn Sie technisch versiert sind, aber nicht die Zeit haben, den gesamten Quellcode zu lesen, ist möglicherweise ein technisches Handbuch erforderlich.

• Wenn dem Benutzer technische Fähigkeiten fehlen, er aber nur wissen muss, was passiert, ist eine Benutzerdokumentation erforderlich.

Die eigentliche Frage ist also, wer Ihr Kunde ist. Wenn ja, reichen selbstdokumentierender Code oder Kommentare aus. Wenn es sich um eine andere Person handelt, möchten Sie möglicherweise die Dokumentation erweitern.

Ja, Kommentare sind eine Form der Dokumentation. Ob es sich um eine nützliche Dokumentation für jemanden handelt, der Ihren Code warten oder aktualisieren muss, ist eine offene Frage.

Ich weiß, du hast es als Wegwerfbeispiel gemeint, aber solche Sachen

print $foo; # this prints "bar"

ist nicht nützlich; es fügt nur visuelle Unordnung hinzu. Dokumentieren Sie nicht das Offensichtliche.

Blockkommentare am Kopf einer Methode oder Funktionsdefinition, die den Zweck der Funktion oder Methode (auf hoher Ebene ), Eingaben, Ausgaben, Rückgabewerte (falls vorhanden), Ausnahmen (falls vorhanden), Vorbedingungen und Nachbedingungen beschreiben, sind nützlich. aber nur in dem Maße, in dem sie jemandem sagen, wie die Funktion oder Methode verwendet werden soll. Sie erklären nicht, warum die Funktion existiert.

Wenn jemand anderes Ihren Code pflegen muss, müssen Sie die Anforderungen und das Design irgendwo dokumentieren, und dies wird normalerweise nicht im Quellcode selbst durchgeführt.

Ich finde, dass das Festhalten an Bob Martins Ansatz von Clean Code normalerweise das Problem löst, ob Sie denken, dass Sie zu viel oder zu wenig kommentieren und die Dokumentation weglassen:

Wir sind Autoren. Und eine Sache über Autoren ist, dass sie Leser haben. In der Tat sind Autoren dafür verantwortlich, gut mit ihren Lesern zu kommunizieren. Wenn Sie das nächste Mal eine Codezeile schreiben, denken Sie daran, dass Sie ein Autor sind, der für Leser schreibt, die Ihre Bemühungen beurteilen.

... liegt das Verhältnis von Lese- und Schreibzeit weit über 10: 1. Wir lesen ständig alten Code, um neuen Code zu schreiben.

Mit anderen Worten, ist Ihr Code ohne die Dokumentation selbsterklärend? Es gibt keine festgelegten Regeln dafür (es sei denn, Sie arbeiten für jemanden wie Microsoft, dessen Dokumentation öffentlich zugänglich ist). Es liegt hauptsächlich daran, dem zukünftigen Leser des Codes zu helfen, der häufig Sie sind.

Die Dokumentation sollte das Warum nicht das Wie dokumentieren . Das Wie sollte im Code selbstverständlich sein, es sei denn, es handelt sich um einen arkanen Optimierungstrick oder eine andere sprachspezifische Technik, die normalerweise nicht vorkommt.

Das Warum sollte wahrscheinlich nicht im Code enthalten sein, es sollte sich an einer anderen Stelle wie einem Produkt-Backlog befinden, das dazu bestimmt ist, Kommentare mit Story-IDs festzuschreiben, nach denen in einem Änderungsprotokoll oder einem Filialnamen gesucht werden kann.

Kommentare sind eine Form der Dokumentation. Eine minderwertige Form, die darauf hindeutet, dass Sie einen Bereich Ihres Codes gefunden haben, der besser berücksichtigt werden kann.

Es hört sich so an, als würden Sie die Dinge zwanghaft kommentieren. Andere Optionen zu haben kann eine gute Sache sein. Ich kann mir drei überlegene Formen der Dokumentation vorstellen:

1) Berücksichtigen Sie Ihren Code besser. Anstatt einen Kommentar hinzuzufügen, extrahieren Sie eine Methode oder Funktion, deren Name der Text des Kommentars ist, den Sie schreiben wollten. Der Code sagt also, was Ihr Kommentar sagen wollte.

2) Tests. Dies ist die Form der Dokumentation, nach der ich normalerweise suche. Unit-Tests und Abnahmetests sind lebende Dokumentationen und können leicht gelesen werden, wenn viele sinnvolle Methoden verwendet werden, um Absichten auszudrücken, wie in Punkt 1.

3) Für Skripte die Option --help. Hier können Sie verrückt nach doc werden. Halten Sie sich an Beispiele und antizipieren Sie, was der Benutzer benötigen würde.

Wenn Sie dazu neigen, einen Kommentar einzugeben, prüfen Sie zusammenfassend, ob es eine Möglichkeit gibt, mit dem Leser zu kommunizieren, indem Sie den Code besser strukturieren. Oder gibt es einen Test, der mitteilt, warum dieser Code vorhanden ist? Wenn Sie immer noch geneigt sind, dies zu kommentieren, geben Sie eine Niederlage zu und tun Sie es.