Die automatische Dokumentationserstellung kann mit einer Vielzahl von Werkzeugen durchgeführt werden, wobei GhostDoc eines der bekanntesten ist. Per Definition ist jedoch alles, was es erzeugt, redundant. Es wirft einen Blick auf Namen von Methoden, Klassen, etc. und gibt Englisch , das könnte sie mehr verbosely erklären. Im besten Fall tut es das, was der Leser bereits im Kopf tun konnte (Beispiele von hier ):
/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...
Im schlimmsten Fall kann es tatsächlich zu bizarren Dokumentationen kommen, die in ihrem Versuch, die Bedeutung von Namen heuristisch herauszufinden, irreführend sind:
/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...
Es scheint , dass die Haltung mit GhostDoc ist, „es ist an mich besser zu haben , eine Art formaler XML - Dokumentation“, aber wenn diese Dokumentation ist zu 100% redundant, warum? Verschwendet es nicht bestenfalls eine Tonne Platz?
An meinem Arbeitsplatz müssen wir alles dokumentieren, und zwar fast immer mit GhostDocs automatisch generierten Dokumenten. Tun Sie dies und gibt es vernünftige Gründe, Code nicht einfach undokumentiert zu lassen, wenn Sie die Dokumentation nicht selbst schreiben wollen?
Antworten:
Nein. Die von GhostDoc generierte Dokumentation ist Boilerplate (ähnlich wie beim Erstellen einer neuen OO-Klasse in einer IDE das Boileplate für eine Klasse mit einem Konstruktor oder etwas anderem erstellt wird). Der nützliche Teil der Dokumentation ist, was nach dem Hinzufügen der Kesselplatte folgen würde.
Während Sie haben an Ihrem Arbeitsplatz dokumentieren alles, so scheint es , Ihre coleagues den perfekten Weg , um es zu finden: einfach so tun.
quelle
In einer statisch typisierten Sprache ist die Dokumentation im Javadoc-Stil nicht für die Autoren, sondern für die Verbraucher bestimmt. Durch die automatische Generierung können die Autoren die Dokumentation für andere Benutzer einfacher verwalten.
Wenn Sie eine statisch typisierte Sprache verwenden und keine Bibliothek für den Verbrauch durch Dritte schreiben, ist die automatische Generierung für Sie wenig interessant und wird meiner Erfahrung nach nur selten verwendet. Wenn Sie eine dynamisch typisierte Sprache verwenden, werden die Typen häufig in einer Dokumentation im Javadoc-Stil dokumentiert, auch für den internen Gebrauch. Die automatische Generierung kennt die Typen jedoch nicht, sodass Sie lediglich das manuelle Kopieren des Boilerplates vermeiden müssen.
Stellen Sie sich Autogeneration auf keinen Fall als ein fertiges Produkt vor. Stellen Sie sich vor, Sie stellen die Kesselplatte für Sie her. Daher sind alle Änderungen, die Sie manuell vornehmen, von Bedeutung.
quelle
Aus wessen Perspektive?
Wenn ich die Firma oder die Entwicklergruppe leite, gibt es keinen guten Grund. Ich stehe fest in dem "Kommentare sollten erklären warum " Lager. Menschen dazu zu zwingen, Klassen / Funktionen / Eigenschaften zu kommentieren, ist schlimmer als wertlos, da sie veraltet sind, den Leser irreführen, als Ausrede dienen, keinen lesbaren Code zu erstellen, und so weiter. Diese Kommentare verschwenden sowohl Zeit damit, sie zu schreiben, den Code zu lesen, als auch durch sie verursachte Fehler. Einige werden argumentieren, dass API-Dokumente im JavaDoc-Stil ein Grund für das Kommentieren sind, aber selbst unter diesem Argument sollte ein kleiner Teil Ihres Codes Teil der öffentlichen API sein, und JavaDoc ist kein Ersatz für tatsächliche API-Dokumente.
Als Entwickler habe ich an einigen Stellen gearbeitet, an denen trotz meiner Meinung Kommentare erforderlich sind . Da ich weder die Zeit noch die Geduld habe, einen Haufen Mist zu schreiben, den niemand verwenden wird, habe ich ihn stattdessen mit GhostDoc geschrieben. So kann ich diese Zeit damit verbringen, Dinge zu tun, die wichtig sind. Weitaus effizienter als eine Änderung der Unternehmenspolitik.
Eine andere gute Sache, die ich mit GhostDoc gefunden habe, ist, dass es als Kontrolle dient, dass meine Namen gut sind. Wenn GhostDoc keine anständige Dokumentation für eine Funktion erstellen kann, ist es ein Geruch, dass meine Funktions- oder Parameternamen möglicherweise schlecht sind. Obwohl ich nicht das Werkzeug für verwenden würde nur das, es ist ein netter kleiner Nebeneffekt , wenn ich sowieso meine Zeit zu verschwenden bin gemacht.
quelle
RichTextSelection_ChangedMethode ist jedoch möglicherweise einfacher zu verwenden, wenn sie zu einem Auswahlobjekt gehört und nicht nach dem Typ ihres Parameters benannt wurde. Obwohl, wie Telastyn sagte, es nur ein Geruch ist, der für Ihr Design richtig oder falsch sein könnte, und meine Vorschläge werden die GhostDoc-Ausgabe wahrscheinlich nicht verbessern.EDIT : Ich habe die ursprüngliche Frage falsch verstanden; Obwohl ich denke, dass das Generieren von Dokumentation (dh Nicht-Code- Dokumenten ) äußerst wertvoll sein kann (siehe Originalantwort zu Doxygen weiter unten), klingt das automatische Generieren von Kommentaren (was GhostDoc tatsächlich tut) für mich verrückt. Ich kann nicht verstehen, warum irgendjemand erwarten würde, dass ein Programm unkommentierten Quellcode lesen und Kommentare schreiben kann, die ihn wirklich klarstellen.
Es ist denkbar , mir , dass ein extrem „smart“ Kommentar-Generation - Dienstprogramm könnte so programmiert werden , bestimmte Muster zu erkennen und „wie“ -Stil Kommentare zu erzeugen; Zum Beispiel könnte es Knuths Algorithmus zur Varianzberechnung erkennen und einen Kommentar abgeben, der erklärt, wie er funktioniert und warum der naive Algorithmus nicht angemessen wäre. Vielleicht könnte ein solches Dienstprogramm sogar so programmiert werden, dass es kanonische objektorientierte Entwurfsmuster erkennt (z. B. Abstract Factory) und Kommentare einfügt, die angeben, welches Muster verwendet wird und welche Klassen welche Rollen spielen.
Aber meiner Meinung nach erklären die nützlichsten Kommentare nicht, "wie" etwas funktioniert, da der Code dies selbst zeigen sollte, sondern " warum " Kommentare, die erklären, "warum" eine bestimmte Sache getan wird. Wie von David Hammen in den Kommentaren unten bemerkt, müsste ein Dienstprogramm die Gedanken des Programmierers lesen, um "Warum" -Kommentare zu generieren. Offensichtlich ist das unmöglich.
Anhand der angegebenen Beispiele scheint GhostDoc jedoch nicht einmal die Aufgabe zu erfüllen, echte "Wie" -Kommentare zu erstellen. So ist es, meiner Meinung nach , schlimmer als nutzlos, da das, was es nicht erzeugt albernen sein kann und irreführend (wie im zweiten Beispiel).
Originale Antwort: Warum automatische Extraktion und Formatierung der Dokumentation eine gute Idee ist
Mein Softwareteam verwendet Doxygen. Der Hauptgrund dafür ist, dass wir eine Dokumentation der Code-Merkmale / Verhaltensweisen / usw. benötigen, die nicht im Quellcode enthalten ist (dh von Nicht-Programmierern gelesen werden kann). Wir halten es jedoch für besser, diese in den Quellcode selbst zu integrieren, als dies zu tun pflegen Sie es als zweites Dokument . Dies hilft uns dabei, die Dokumentation mit dem Quellcode synchron zu halten (obwohl dies natürlich nie vollständig sichergestellt werden kann, viel weniger automatisiert) und den Aufwand für das Schreiben von Dokumentation zu minimieren (da die Dokumentation für ein Codeteil trivial in den Quellcode integriert werden kann) Datei mit dem Code selbst).
Daher liegt der Fokus unserer Verwendung von Doxygen nicht darauf, Informationen aus dem Code selbst zu extrahieren, sondern die Dokumentation des Quellcodes so nah wie möglich am Quellcode selbst zu halten.
Auf diese Weise können wir mit einem einzigen Tool sowohl eine "Betriebstheorie" erstellen, die unsere gesamte Codebasis beschreibt, als auch mehrere Sätze von "Versionshinweisen", die das Softwareprodukt beschreiben, in der Tat jedoch keine eigentliche "Codedokumentation" enthalten typischer Sinn.
Es gibt zwei Gründe, warum wir eine Dokumentation des Verhaltens unseres Codes benötigen, die nicht aus dem Quellcode stammt:
Beachten Sie, dass der zweite Aufzählungspunkt dem Punkt ziemlich ähnlich ist, den ein paar andere Antworten zu Managern gemacht haben, die die Gewissheit (/ prahlen Rechte) haben wollen, dass für jedes Stück Quellcode eine Dokumentation (unabhängig von der Qualität) vorhanden ist. Diese Art der Gestaltung ignoriert jedoch die Tatsache, dass extern vorgeschriebene Dokumentation tatsächlich einige legitime Vorteile haben kann.
quelle
Eine automatisierte Dokumentation ist sicherlich besonders hilfreich, wenn sie aufschlussreiche, geeignete Beschreibungen der Code-Autoren wiedergeben kann. Ansonsten ist es nur ein verherrlichter automatischer Formatierer.
Die Formatierung ist jedoch nicht nutzlos. Es ist von Wert, die öffentlichen Methoden einer großen Komponente auf einen Blick zu finden, zu sortieren und garantiert vollständig zu sein. Wenn Sie einen
frobnickMutator benötigen und dieser nicht vorhanden ist, wissen Sie, dass er nicht vorhanden ist, ohne durch den Quellcode zu waten. (Negative Ergebnisse haben auch einen Wert: Sie wissen, dass Sie etwas tun müssen, und Sie haben mehr Zeit dafür, weil Sie nicht waten mussten.)Ja, die automatische Dokumentenerstellung bietet also einen Mehrwert. Mit Sicherheit nicht so viel, wie Manager wahrscheinlich annehmen, und normalerweise nicht einmal so viel, wie ein wirklich guter Redakteur annehmen würde, aber nichts.
quelle
frobnickMutatoren wissen muss, wird ein Softwareentwickler sein. Sie verstehen möglicherweise nicht, wie sie den Quellcode durchsehen müssen (was Vertrautheit mitgrep/cscope/ack/ etc erfordert ), und selbst wenn sie die richtige Datei finden, ist der eigentliche Quellcode möglicherweise nicht einfach zu lesen, selbst wenn er gut kommentiert ist aus einer SW-Perspektive. Die Möglichkeit, einen Index zu durchsuchen oder in eine Suchleiste einzugeben und dann Text zu durchsuchen, der aussieht, als wäre er Teil einer Webseite, kann sehr wertvoll sein.In dieser Form ist es schlimmer als nutzlos, aber nur, weil es sich nur auf die öffentliche Signatur stützt (die im Fall von Javadoc ohnehin für jeden sichtbar ist, der das API-Dokument liest).
Es ist jedoch möglich, automatisierte Dokumentationswerkzeuge zu schreiben, die auch den Inhalt der Methode berücksichtigen. Als Proof of Concept habe ich ein kleines Eclipse-Plugin geschrieben, das dem Javadoc eine Liste anderer Methoden hinzufügt, die von der dokumentierten Methode aufgerufen werden. (Natürlich können Sie nicht bei jedem Aufruf Filter definieren, z. B. nach Paket.)
Und ich habe es tatsächlich als sehr praktisch empfunden, wenn ich mir eine völlig unbekannte Codebasis vorstelle. Zugegeben, es ist ein sehr begrenzter Anwendungsfall, aber es war definitiv eine Hilfe.
Basierend auf dieser Erfahrung lautet die Antwort auf die Frage: Ja, aber wir brauchen viel intelligentere Werkzeuge.
Update: Natürlich ist eine zusätzliche Frage (eine, die gestellt werden sollte, bevor irgendeine Art von Dokumentation geschrieben wird), wer die Zielgruppe ist. Wenn wir eine öffentliche API für Clients dieser API dokumentieren, ist das Hinzufügen all dieser Implementierungsdetails ein großes Nein, da alles, was Sie in Javadoc einfügen, technisch Teil der API ist.
Wenn das Zielpublikum jedoch andere Entwickler sind, die an demselben Produkt arbeiten, ist das automatische Hinzufügen von Informationen zu Implementierungsdetails, z. B. welche Methoden ein bestimmtes Feld ändern oder lesen, sowohl akzeptabel als auch recht nützlich.
quelle
Ich kenne keine anderen Umgebungen, aber wenn es um große (oft Open Source) PHP-Projekte geht, die andere geschrieben haben, ist phpXRef ein absoluter Lebensretter (insbesondere, wenn das Dokument online gestellt wird und Google es indizieren kann).
Sogar ein schlecht kommentiertes Projekt kann mir zumindest helfen, herauszufinden, wo Dinge definiert wurden und wo sie verwendet werden (zum Beispiel beim Refactoring).
Wenn gut kommentiert, bilden die resultierenden Seiten fast eine perfekte Bibel für die Codebasis (für meine Zwecke sowieso).
Darüber hinaus generiert meine bevorzugte IDE automatisch den Kommentarblock (wenn ich / ** eingebe), der ungefähr 75% der Kommentierungsarbeit für mich erledigt. Es ist erstaunlich, wie viele dumme Dinge ich im Laufe meines Programmierlebens nicht mehr ausführen konnte, nur weil ich anderen (und zukünftigen) Leuten erklären musste, was ich tue. Wenn mein Kommentar für den Dokumentgenerator größer ist als die Methode, bedeutet dies normalerweise, dass ich nicht genug Kaffee getrunken habe und vielleicht etwas härter darüber nachdenken möchte.
Diese selbstgleichen Kommentarblöcke erstellen auch den Inline-Vervollständigungs- "Hilfetext", damit ich genau sehen kann, was (von den anderen Programmierern) beim Schreiben des Funktionsaufrufs erwartet wurde. Dies ist ein enormer Produktivitätsschub für mich (insbesondere in den seltenen Fällen, in denen ein anderer hilfreicher Entwickler "Um Himmels willen, mache / mache nicht X" geschrieben hat - was eine Menge Schmerz ersparen kann.
Ich kann gar nicht genug betonen, wie nützlich es ist, die erwarteten Eingabetypen in komplexen (und häufig falsch benannten) PHP-Projekten und die Argumentreihenfolge in weniger häufig verwendeten Methoden anzugeben. Selbst mit meinem eigenen Code kann ich mich nicht immer daran erinnern, welche Argumente ich für etwas angegeben habe, das ich in einem Alter nicht angerührt habe.
In einem Fall bedeutete dies, dass die Ursache der wiederkehrenden Probleme darin bestand, dass aus irgendeinem Grund, der sich schlecht auf frühere Entwickler auswirkt, einige Funktionen und sogar Konstanten an einer großen Anzahl von Stellen definiert wurden (mit einem gewissen Grad an Inkonsistenz für zusätzlichen "Spaß"). . Das war das Zeichen, sich vom Projekt zu entfernen.
In größeren Projekten, die vor meiner Teilnahme begonnen haben, kann ich sehen, welcher Entwickler (vorausgesetzt, er hat die Klassendatei mit einem Namen und einer E-Mail versehen) die Klasse erstellt. Es ist sehr hilfreich, einfach den richtigen Entwickler zu finden und mit ihm zu sprechen.
Automatische Aufgabenlisten - Die Verwendung des @ todo-Tags (häufig in Projekten, in denen ich arbeite) bedeutet, dass in der Dokumentation nachverfolgt werden kann, was mehr Arbeit erfordert (oder nachgewiesene fehlende Funktionen). Wieder verfolgt meine IDE dies und das allein als eine gute Anleitung, was zuerst meine Aufmerksamkeit benötigt.
Schließlich (und für mich sehr wichtig) wird der nicht triviale Aufwand beseitigt, all das auszuschreiben und dann zu versuchen, es auf dem neuesten Stand zu halten, wenn einige (viele gelesene) Programmierer Änderungen vornehmen und nicht mit den Betreuern der Dokumentation sprechen.
Die Gründe dafür sind:
Unterschätzen Sie auch nicht, wie wichtig es ist, spitze Chefs auf Knopfdruck bei Laune zu halten.
Kurz gesagt, die "Kommentare zur automatischen Dokumentation" sind für meine Codierungsgewohnheiten von entscheidender Bedeutung. Ich bin mir sicher, dass es viele gibt, die das für lahm halten, aber ich bin mir auch genauso sicher, dass es ein paar Leute gibt, die genau wissen, was ich sage. Ich weiß nicht, wie ich überlebt habe, bevor ich phpXRef (und meine Lieblings-IDE) entdeckt habe.
quelle
Es ist oft gut, Dokumentationsgeneratoren zu verwenden, um Boilerplate- oder "Stand-In" -Kommentare zu erstellen, die später von den tatsächlichen Entwicklern überarbeitet werden. Ich benutze oft die Auto-JavaDoc-Funktion von Eclipse, um den Kopfkommentar mit bereits ausgefüllten Parametertypen und Rückgabewerten zu generieren, und füge dann einfach das "Fleisch" der Dokumentation hinzu.
quelle
Als C # -Entwickler verwende ich Stylecop, das Kommentare für alle Klassen, Methoden usw. vorschreibt. Diese Kommentare erstelle ich automatisch mit einem Tool. In den meisten Fällen sind die vom Tool generierten Kommentare ausreichend und können über den Namen des Objekts abgeleitet werden, z. B. über eine Personenklasse und ein ID-Feld.
Aber wenn ich eine nicht naheliegende Methode weiter kommentieren möchte, ist es sehr einfach, die Dokumentation des Kesselplattens und einige Erklärungen zu ihrer Funktion zu erweitern. Als Beispiel: Ich habe eine Methode für meine Person-Klasse, die Vorname + Nachname zurückgibt, aber ich habe ein wenig Dokumentation darüber hinzugefügt, was passiert, wenn eine von beiden fehlt.
Kurz gesagt: Ich denke, dass die Boilerplate-Dokumentation schädlich sein kann, wenn Sie niemals den vom Generator bereitgestellten Text ändern. In diesem Fall handelt es sich nur um Leitungsrauschen. Wenn Sie sie jedoch als Vorlage betrachten, senken Sie die Messlatte, um gute und nützliche Kommentare für sich selbst oder Ihre Kunden bereitzustellen. Könnten Sie die Kommentare schreiben, ohne sie automatisch zu generieren? Sicher, aber Sie müssten sich an das Format halten (das in C # -Fällen ziemlich ausführlich und lästig ist, wenn Sie es von Hand generieren), und das verringert die Wahrscheinlichkeit, dass Sie diesen Kommentar wirklich bei al ..
quelle
Vermeiden Sie Tautologie
Das einzige Mal, dass Sie irgendeine Art von Dokumentation für Code benötigen sollten, ist zu erklären, warum eine Methode / Funktion etwas tut. Der Name sollte für das, was sie tut, ausreichen .
Wenn Sie etwas tun, das nicht idiomatisch ist oder gegen den Grundsatz des geringsten Erstaunens verstößt, ist Dokumentation erforderlich.
Automatisch generierte Dokumentation, die nur ein Formatierer für die Ausgabe von Informationen ist, wird von den Verbrauchern Ihres Codes fast verlangt. Javadoc macht das sehr gut.
Nicht alles sollte manuell dokumentiert werden
Dinge wie getXXX / setXXX-Methoden sollten selbsterklärend sein, sodass eine automatisch generierte Dokumentation, die nur anzeigt, dass sie existiert, gut aufgenommen wird.
quelle
Die Codedokumentation, zumindest die "automatische" Art, ist der kleinste gemeinsame Nenner für Personen, die versuchen, die Anwendung zu verstehen.
Die erfahrensten Benutzer würden eine automatische Codedokumentation nicht schätzen. Sie hätten viel lieber eine "gezielte" Dokumentation, die ihnen sagt, was (wenig) ihnen gesagt werden muss.
Die am wenigsten erfahrenen Benutzer würden es aus dem entgegengesetzten Grund nicht schätzen. sie würden es sowieso nicht verstehen.
Die "wertschätzendsten" Benutzer der automatischen Codedokumentation sind diejenigen, für die "ein wenig Wissen" eine gefährliche Sache ist. "Sie können die Dokumentation verstehen oder auch nicht (obwohl sie dies wahrscheinlich tun), aber sie werden sich wohl fühlen, wenn sie" sind " auf dem Laufenden gehalten. "Diese Zielgruppe umfasst die meisten" Manager "-Typen. Wenn dies Ihre Hauptzielgruppe ist, ist eine automatische Codedokumentation möglicherweise eine gute Sache.
quelle
Die einfache Antwort auf "Warum Dokumente generieren" kann einfach durch Anzeigen von MSDN beantwortet werden.
Stellen Sie sich vor, Sie möchten ein Programm schreiben, das eine Bibliothek verwendet, in der es keine API-Dokumentation gibt. Es wäre ein Albtraum. MSDN ist ein hervorragendes Beispiel für die Art von Dokument, das aus Quellcode und Kommentaren generiert werden kann und eine wichtige Ressource für Entwickler darstellt.
Wenn Sie eine Anwendung schreiben (dh keine Bibliothek, die von anderen konsumiert werden soll), gibt es vielleicht einen Grund, warum es Sie nicht stört - aber selbst dann enthält die Menge einer großen, nur internen Anwendung nicht viele Bibliotheken sowieso? Wenn Sie einem solchen Team beitreten, ist es hilfreich, ein durchsuchbares API-Dokument zu haben.
Kein Tool wird Ihre Dokumentation für Sie schreiben, aber es gibt Ihnen das Boilerplate, das Sie ohnehin manuell ausschreiben müssten. Einige Tools (wie Doxygen) generieren auch Diagramme und Referenzlisten (zum Beispiel von aufgerufenen und aufrufenden Funktionen) ), die selbst beim Betrachten des Quellcodes nicht leicht zu entdecken wären.
Offensichtlich sollte pragmatischer gesunder Menschenverstand auf das angewendet werden, was dokumentiert wird. Eigenschaften und untergeordnete Funktionen können ignoriert (und sogar in den Tools von der Generierung übersprungen werden), aber zu keinem Zeitpunkt sollte jemand sagen, dass es den Quellcode gibt, der Dokumentation genug ist .
quelle