it-swarm.com.de

Gibt es einen logischen Grund, die Codedokumentation automatisch zu generieren?

Die automatische Erstellung von Dokumentationen kann mit einer Vielzahl von Tools durchgeführt werden, wobei GhostDoc eines der bekanntesten ist. Per Definition ist jedoch alles, was es erzeugt, redundant. Es wirft einen Blick auf die Namen von Methoden, Klassen usw. und gibt Englisch aus, das könnte ausführlicher erklärt. Im besten Fall macht es das, was der Leser bereits in seinem Kopf tun konnte (Beispiele aus 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 bei dem 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 Einstellung bei GhostDoc lautet: "Es ist an sich besser, eine Art formale XML-Dokumentation zu haben", aber wenn diese Dokumentation zu 100% redundant ist, warum? Verschwenden Sie nicht bestenfalls eine Menge Platz?

An meinem Arbeitsplatz müssen wir alles dokumentieren, und zwar fast immer mit den automatisch generierten GhostDoc-Dokumenten. Tun Sie dies und gibt es vernünftige Gründe, Code nicht einfach undokumentiert zu lassen, wenn Sie die Dokumentation nicht selbst schreiben?

60
Jez

[...] dokumentieren Sie alles und fast immer mit den automatisch generierten GhostDoc-Dokumenten. Tun Sie dies und gibt es vernünftige Gründe, Code nicht einfach undokumentiert zu lassen, wenn Sie die Dokumentation nicht selbst schreiben?

Nein. Die von GhostDoc generierte Dokumentation ist Boilerplate (ähnlich wie beim Erstellen einer neuen OO Klasse in einer IDE erstellt die Boileplate für eine Klasse mit einem Konstruktor oder so) ). Der nützliche Teil der Dokumentation ist, was nach dem Hinzufügen der Boilerplate folgen würde.

Während Sie müssen alles an Ihrem Arbeitsplatz dokumentieren, scheinen Ihre Kollegen den perfekten Weg gefunden zu haben: tun Sie einfach so.

14
utnapistim

In einer statisch typisierten Sprache ist die Dokumentation im Javadoc-Stil nicht für die Autoren, sondern für die Verbraucher. Die automatische Generierung erleichtert es den Autoren lediglich, die Dokumentation für andere Benutzer zu verwalten.

Wenn Sie eine statisch typisierte Sprache verwenden und keine Bibliothek für den Verbrauch durch Dritte schreiben, bringt Ihnen die automatische Generierung nicht viel und wird meiner Erfahrung nach selten verwendet. Wenn Sie eine dynamisch typisierte Sprache verwenden, wird häufig eine Dokumentation im Javadoc-Stil verwendet, um die Typen zu dokumentieren, auch nur für den internen Gebrauch. Die automatische Generierung kennt die Typen jedoch nicht. Sie sparen also nur das manuelle Kopieren der Boilerplate.

Stellen Sie sich die Generierung in keinem Fall als Herstellung eines fertigen Produkts vor. Stellen Sie sich vor, Sie produzieren die Heizplatte für Sie. Daher sind alle Änderungen, die Sie manuell vornehmen, von Bedeutung.

73
Karl Bielefeldt

Gibt es einen logischen Grund, die Codedokumentation automatisch zu generieren?

Aus wessen Perspektive?

Wenn ich die Firma oder die Entwicklergruppe leitete, gibt es keinen guten Grund. Ich bin fest im Lager "Kommentare sollten erklären warum ". Menschen dazu zu zwingen, Klassen/Funktionen/Eigenschaften zu kommentieren, ist schlimmer als wertlos, da sie veraltet sind, den Leser irreführen, als Entschuldigung dafür dienen, keinen lesbaren Code zu erstellen und so weiter. Diese Kommentare verschwenden Zeit damit, sie zu schreiben, den Code zu lesen und Fehler zu verursachen. 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, für die Kommentare erforderlich sind, trotz meiner Meinung. Da ich nicht die Zeit oder Geduld habe, einen Haufen Mist zu schreiben, den niemand benutzen wird, habe ich ihn stattdessen GhostDoc. Dadurch kann ich diese Zeit damit verbringen, Dinge zu tun, die wichtig sind. Weitaus effizienter als die Änderung der Unternehmenspolitik.

Eine andere gute Sache, die ich mit GhostDoc gefunden habe, ist, dass es als Überprüfung dient, ob meine Namen gut sind. Wenn GhostDoc keine anständige Dokumentation für eine Funktion generieren kann, ist es ein Geruch, dass meine Funktions- oder Parameternamen möglicherweise schlecht sind. Obwohl ich das Tool nicht nur für verwenden würde, ist es ein netter kleiner Nebeneffekt, wenn ich sowieso meine Zeit verschwenden muss.

26
Telastyn

[~ # ~] edit [~ # ~] : Ich habe die ursprüngliche Frage falsch verstanden; Obwohl ich denke, dass das Generieren von Dokumentationsdokumenten (dh Nicht-Code-Dokumenten ) äußerst wertvoll sein kann (siehe Originalantwort zu Doxygen unten), automatisch -generierende Kommentare (was GhostDoc tatsächlich tut) klingen für mich verrückt. Ich kann nicht verstehen, warum jemand von einem Programm erwarten würde, dass es nicht kommentierten Quellcode lesen und Kommentare schreiben kann, die es wirklich klarstellen.

Es ist für mich denkbar, dass ein äußerst "intelligentes" Dienstprogramm zur Kommentargenerierung programmiert werden könnte, um bestimmte Muster zu erkennen und Kommentare im "wie" -Stil zu generieren. Zum Beispiel könnte es Knuths Varianzberechnungsalgorithmus erkennen und einen Kommentar abgeben, der erklärt, wie es funktioniert und warum der naive Algorithmus nicht geeignet wäre. Möglicherweise könnte ein solches Dienstprogramm sogar so programmiert werden, dass kanonische objektorientierte Entwurfsmuster (z. B. Abstract Factory) erkannt und Kommentare eingefügt werden, 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 selbst dies zeigen sollte, sondern " warum " Kommentare, die "warum" erklären a besondere Sache wird getan. Wie von David Hammen in den Kommentaren unten erwähnt, müsste ein Dienstprogramm "die Gedanken des Programmierers lesen", um "Warum" -Kommentare zu generieren. Offensichtlich ist das unmöglich.

Anhand der angegebenen Beispiele scheint es jedoch, dass GhostDoc nicht einmal die Aufgabe erfüllt, echte Kommentare im "Wie" -Stil zu erstellen. Meiner Meinung nach ist es also schlimmer als nutzlos, da das, was es erzeugt, verrückt und irreführend sein kann (wie im zweiten Beispiel).


Ursprüngliche Antwort: Warum das automatische Extrahieren und Formatieren der Dokumentation eine gute Idee ist

Mein Software-Team verwendet Doxygen. Der Hauptgrund dafür ist, dass wir Nicht-Quellcode (dh für Nicht-Programmierer lesbar) Dokumentation der Code-Funktionen/Verhalten/etc benötigen, aber Wir halten es für eine bessere Praxis, dies in den Quellcode selbst zu integrieren, als es als zweites Dokument zu pflegen . Dies hilft uns, die Dokumentation mit dem Quellcode synchron zu halten (obwohl dies natürlich nie vollständig sichergestellt werden kann, viel weniger automatisiert) und minimiert den Aufwand für das Schreiben von Dokumentation (da die Dokumentation für einen Teil des Codes trivial in den Code integriert werden kann Datei mit dem Code selbst).

Daher liegt der Schwerpunkt unserer Doxygen-Verwendung 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 auch ein einziges Tool verwenden, um sowohl eine "Betriebstheorie" zu erstellen, die unsere gesamte Codebasis beschreibt, als auch mehrere Sätze von "Versionshinweisen", die das Softwareprodukt beschreiben, aber tatsächlich keine tatsächliche "Codedokumentation" in der typischer Sinn.

Es gibt zwei Gründe, warum wir eine Dokumentation des Verhaltens unseres Codes ohne Quellcode benötigen würden:

  • Unser Produkt ist nicht nur Software; Es ist ein komplexes Tool, das viele Hardwarekomponenten integriert, darunter einige ausgefallene Laser und Fluidik. Wir brauchen Ingenieure ohne viel Software-Hintergrund, um genau zu verstehen, wie sich die Interna unseres Codes genau verhalten , und wenn wir ihnen sagen, dass sie den Quellcode lesen sollen, wird dies nicht erreicht.
  • Wir müssen einige Qualitätsvorschriften befolgen, von denen einige intern vom Unternehmen und andere gesetzlich von der Bundesregierung vorgeschrieben sind. Obwohl der Qualitätsprozess äußerst wertvoll und hilfreich ist (oder zumindest sein kann), ist er mit einem nicht zu vernachlässigenden Aufwand verbunden. Ein Teil davon ist Aufgabe des Softwareteams, diese Art der detaillierten Dokumentation der Software bereitzustellen. Die Integration dieser Dokumentation in den Code selbst minimiert den Overhead und hilft uns, die Dokumentation auf dem neuesten Stand zu halten.

Beachten Sie, dass der zweite Aufzählungspunkt dem Punkt ziemlich ähnlich ist, den einige andere Antworten zu Managern gegeben haben, die die Sicherheit (/ Prahlerei) wünschen, zu wissen, dass für jeden Quellcode eine Dokumentation (unabhängig von der Qualität) vorhanden ist. Diese Art der Gestaltung ignoriert jedoch die Tatsache, dass extern vorgeschriebene Dokumentationen tatsächlich einige legitime Vorteile haben können.

21
Kyle Strand

Natürlich ist eine automatisierte Dokumentation besonders hilfreich, wenn sie aufschlussreiche, angemessene Beschreibungen der Code-Autoren reproduzieren kann. Ansonsten ist es nur ein verherrlichter automatischer Formatierer.

Die Formatierung ist jedoch nicht nutzlos. Es ist wertvoll, die öffentlichen Methoden einer größeren Komponente auf einen Blick zu finden, sortiert und garantiert vollständig zu sein. Wenn Sie einen frobnick -Mutator benötigen und dieser nicht vorhanden ist, wissen ist er nicht vorhanden, ohne den Quellcode zu durchsuchen. (Negative Ergebnisse haben auch Wert: Sie wissen, dass Sie etwas tun müssen, und Sie haben mehr Zeit dafür, weil Sie nicht waten mussten.)

Ja, die automatische Dokumentgenerierung fügt also einige Werte hinzu. Sicherlich nicht so viel, wie Manager wahrscheinlich annehmen, und normalerweise nicht einmal so viel wie ein wirklich guter Redakteur, aber nicht nichts.

7
Kilian Foth

Ich weiß nichts über andere Umgebungen, aber wenn es um große (oft Open Source) PHP Projekte geht, die andere Leute geschrieben haben, ist phpXRef ein absoluter Lebensretter (besonders wenn das Dokument online gestellt wird) und Google kann es indizieren).

Selbst ein schlecht kommentiertes Projekt kann mir zumindest helfen, herauszufinden, wo Dinge definiert wurden und wo sie verwendet werden (zum Beispiel beim Refactoring).

Wenn sie gut kommentiert sind, bilden die resultierenden Seiten fast eine perfekte Bibel für die Codebasis (für meine Zwecke sowieso).

Außerdem generiert mein bevorzugtes IDE automatisch den Kommentarblock (wenn ich/** eingebe), der ungefähr 75% der Kommentararbeit für mich erledigt. Es ist erstaunlich, wie viele dumme Dinge ich habe Ich wurde im Laufe meines Codiererlebens davon abgehalten, mich zu verpflichten, nur weil ich anderen Leuten (und mir in Zukunft) 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 möchten Sie etwas härter nachdenken.

Diese gleichen Kommentarblöcke erstellen auch den Inline-Vervollständigungstext "Hilfe", damit ich genau sehen kann, was (von den anderen Codierern) erwartet wurde, während ich den Funktionsaufruf schreibe. Dies ist ein massiver Produktivitätsschub für mich (insbesondere in den seltenen Edge-Fällen, in denen ein anderer hilfreicher Entwickler "um Himmels willen do/do-not X" geschrieben hat - was viel Schmerz ersparen kann.

Ich kann nicht genug betonen, wie nützlich es ist, die erwarteten Eingabetypen in komplexen (und oft schlecht benannten) PHP Projekte und die Argumentreihenfolge in weniger häufig verwendeten Methoden) anzugeben. Selbst mit meinem eigenen Code, Ich kann mich nicht immer daran erinnern, welche Argumente ich für etwas angegeben habe, das ich in einer Zeit nicht berührt habe.

In einem Fall bedeutete dies, dass die Ursache für die wiederkehrenden Probleme darin bestand, dass aus irgendeinem Grund, der sich schlecht auf frühere Entwickler auswirkt, einige Funktionen und sogar Konstanten an einer Vielzahl 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 meinem Beitritt gestartet wurden, kann ich sehen, welcher Entwickler (vorausgesetzt, er hat die Klassendatei mit einem Namen und einer E-Mail-Adresse versehen) die Klasse erstellt hat, und es ist äußerst hilfreich, einfach den richtigen Entwickler zu finden und mit ihm zu sprechen.

Automatische Aufgabenlisten - Die Verwendung des @ toodo-Tags (häufig bei Projekten, in denen ich arbeite) bedeutet, dass in der Dokumentation nachverfolgt werden kann, wo weitere Arbeiten erforderlich sind (oder welche Funktionen als fehlend anerkannt sind). Wiederum verfolgt mein IDE dies und das allein als gute Anleitung, was meine Aufmerksamkeit zuerst benötigt.

Schließlich (und für mich sehr wichtig) entfällt der nicht triviale Aufwand, all das aufzuschreiben und dann zu versuchen, es auf dem neuesten Stand zu halten, wenn einige (viele) Codierer Änderungen vornehmen und nicht mit den Dokumentationsbetreuern sprechen.

Die Gründe sind also :

  • Sparen Sie späteren Entwicklern viel Zeit.
  • Verfolgen, wo Funktionen aufgerufen (und definiert) werden,
  • Dumme Codierung erkennen,
  • Finden (wie ein anderer betont hat), wenn offensichtlich etwas fehlt,
  • Vereinfachung des Refactorings (nie viel Spaß)
  • (In vielen Fällen) eine Vorstellung davon bekommen, was der Entwickler versucht hat (vorausgesetzt, er oder sie hat einige Notizen hinterlassen).
  • Wenn das Projekt komplex genug ist, um mehrere Lizenzen zu haben (kein Spaß), kann ich schnell erkennen, welche Lizenzen für einen bestimmten Abschnitt gelten. Zugegeben, das ist ein Nebenbonus.
  • Eine Vorstellung davon bekommen, mit wem Sie über eine Projektdatei sprechen können.
  • Automatische Aufgabenlisten

Unterschätzen Sie auch nicht den Wert, spitze Chefs auf Knopfdruck glücklich zu machen.

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.

In dieser Form ist es schlimmer als nutzlos, aber nur, weil es nur auf der öffentlichen Signatur beruht (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 Hauptteil der Methode berücksichtigen. Als Proof of Concept habe ich ein lahmes 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 fand es tatsächlich ziemlich praktisch, wenn ich mental eine völlig unbekannte Codebasis abbildete. 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.

pdate : 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-Nein, da alles, was Sie in Javadoc eingeben, technisch Teil der API ist.

Wenn die Zielgruppe 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 ziemlich nützlich.

6
biziclop

Es ist oft gut, Dokumentationsgeneratoren zu verwenden, um Boilerplate- oder "Stand-in" -Kommentare zu erstellen, die später von tatsächlichen Entwicklern überarbeitet werden. Ich verwende häufig die Auto-JavaDoc-Funktion von Eclipse, um den Header-Kommentar mit bereits ausgefüllten Parametertypen und Rückgabewerten zu generieren und dann einfach das "Fleisch" der Dokumentation hinzuzufügen.

4
TMN

Als C # -Entwickler verwende ich Stylecop, das Kommentare für alle Klassen, Methoden usw. vorschreibt. Ich generiere diese Kommentare automatisch mit einem Tool. Meistens sind die vom Werkzeug erzeugten Kommentare ausreichend und können durch den Namen des Objekts abgeleitet werden, z. Eine Personenklasse hat ein ID-Feld.

Wenn ich jedoch eine nicht offensichtliche Methode weiter kommentieren möchte, ist es sehr einfach, die Dokumentation der Boilerplate und einige Erklärungen zu ihrer Funktionsweise 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, das Boilerplate-Dokument kann sich nachteilig auswirken, wenn Sie den vom Generator bereitgestellten Text niemals ändern. In diesem Fall ist es nur Leitungsrauschen. Wenn Sie sie jedoch als Vorlage betrachten, senken sie die Messlatte für gute und nützliche Kommentare für sich selbst oder Ihre Verbraucher. Könnten Sie die Kommentare schreiben, ohne sie automatisch zu generieren? Sicher, aber Sie müssten sich an das Format halten (das im C # -Fall ziemlich ausführlich und ärgerlich ist, es von Hand zu generieren), und das verringert die Wahrscheinlichkeit, dass Sie diesen Kommentar überhaupt abgeben.

3
Christian Sauer

Vermeiden Sie Tautologie

Das einzige Mal, wenn Sie irgendeine Art von Dokumentation für Code benötigen sollten, ist zu erklären, warum eine Methode/Funktion tut etwas, der Name sollte ausreichen für was es ist tun.

Wenn Sie etwas tun, das nicht idiomatisch ist oder gegen das Prinzip des geringsten Erstaunens verstößt, ist eine 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, damit automatisch generierende Dokumentationen, die Sie nur darüber informieren, dass sie existieren, gut aufgenommen werden.

3
user7519

Die Codedokumentation, zumindest die "automatische", ist der kleinste gemeinsame Nenner für Personen, die versuchen, die Anwendung zu verstehen.

Die anspruchsvollsten Benutzer würden die 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 nicht (obwohl sie dies wahrscheinlich tun), aber sie werden sich gut fühlen, wenn sie" sind " auf dem Laufenden gehalten. "Diese Zielgruppe umfasst die meisten" Management "-Typen. Wenn dies Ihre Hauptzielgruppe ist, ist eine automatische Codedokumentation möglicherweise eine gute Sache.

2
Tom Au

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, für die keine API-Dokumentation vorhanden ist. Es wäre ein Albtraum. MSDN ist ein großartiges 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 verwendet werden soll), gibt es möglicherweise einen Grund, sich nicht darum zu kümmern - aber selbst dann enthält eine große, nur interne Anwendung keine Reihe von Bibliotheken wie auch immer? Wenn Sie einem solchen Team beitreten, ist es hilfreich, über ein durchsuchbares API-Dokument zu verfügen.

Kein Tool wird Ihre Dokumentation für Sie schreiben, aber sie geben Ihnen das Boilerplate, das Sie ohnehin manuell schreiben müssten. Einige Tools (wie doxygen) generieren auch Diagramme und Referenzlisten (z. B. aufgerufene und aufrufende Funktionen) ), die selbst bei Betrachtung des Quellcodes nicht leicht zu entdecken wären.

Natürlich sollte pragmatischer gesunder Menschenverstand auf das angewendet werden, was dokumentiert wird, Eigenschaften und kleinere Funktionen können ignoriert werden (und sogar in den Tools von der Generierung übersprungen werden), aber zu keinem Zeitpunkt sollte jemand sagen "Es gibt den Quellcode, das ist Dokumentation genug" zu jeder Zeit .

0
gbjbaanb