Hyperlinked, externalisierte Quellcodedokumentation [geschlossen]

Warum binden wir Beschreibungen des Quellcodes in natürlicher Sprache (dh den Grund, warum eine Codezeile geschrieben wurde) immer noch in den Quellcode ein und nicht als separates Dokument?

Angesichts der umfangreichen Immobilien, die modernen Entwicklungsumgebungen (hochauflösende Monitore, Doppelmonitore usw.) geboten werden, könnte eine IDE Semi-Lock-Step-Panels bereitstellen, bei denen der Quellcode visuell von - getrennt, aber eng mit - verknüpft ist. die entsprechenden Kommentare. Beispielsweise könnten Entwickler Quellcodekommentare in einer Hyperlink-Markup-Sprache schreiben (Verknüpfung mit zusätzlichen Softwareanforderungen), wodurch gleichzeitig verhindert wird, dass die Dokumentation den Quellcode überfüllt.

Welche Mängel würden einen solchen Softwareentwicklungsmechanismus verhindern?

Ein Modell zur Klärung der Frage:

Wenn sich der Cursor an einer bestimmten Zeile im Quellcode befindet (oben mit blauem Hintergrund dargestellt), wird die Dokumentation hervorgehoben, die der Zeile am Cursor entspricht (dh von den anderen Details unterschieden wird). Wie in der Frage erwähnt, bleibt die Dokumentation mit dem Quellcode im Gleichschritt, wenn der Cursor durch den Quellcode springt. Ein Hotkey kann zwischen "Dokumentationsmodus" und "Entwicklungsmodus" wechseln.

Mögliche Vorteile sind:

• Mehr Quellcode und mehr Dokumentation auf den Bildschirmen gleichzeitig
• Möglichkeit, die Dokumentation unabhängig vom Quellcode zu bearbeiten (unabhängig von der Sprache?)
• Schreiben Sie Dokumentation und Quellcode parallel, ohne Konflikte zusammenzuführen
• Hyperlink-Dokumentation in Echtzeit mit hervorragender Textformatierung
• Quasi-Echtzeit-Maschinenübersetzung in verschiedene natürliche Sprachen
• Jede Codezeile kann eindeutig mit einer Aufgabe, einer Geschäftsanforderung usw. verknüpft werden.
• Die Dokumentation kann automatisch einen Zeitstempel erstellen, wenn jede Codezeile geschrieben wird (Metriken).
• Dynamische Aufnahme von Architekturdiagrammen, Bildern zur Erklärung von Zusammenhängen usw.
• Dokumentation aus einer Hand (z. B. Tag-Code-Schnipsel zur Aufnahme in das Benutzerhandbuch).

Hinweis:

• Das Dokumentationsfenster kann ausgeblendet werden
• Der Workflow zum Anzeigen oder Vergleichen von Quelldateien wäre nicht betroffen
• Wie die Implementierung erfolgt, ist ein Detail. Die Dokumentation könnte sein:
  • am Ende der Quelldatei aufbewahrt;
  • durch Konvention in zwei Dateien aufgeteilt ( filename.c, filename.c.doc); oder
  • vollständig datenbankgesteuert
• Mit Hyperlink-Dokumentation meine ich die Verknüpfung mit externen Quellen (wie StackOverflow oder Wikipedia) und internen Dokumenten (dh einem Wiki in einer Subdomain, die auf die Dokumentation der Geschäftsanforderungen verweisen könnte) und anderen Quelldateien (ähnlich wie JavaDocs).

Verwandte Themen: Was ist mit der Abneigung gegen Dokumentation in der Branche?

Dieses Problem stört mich die ganze Zeit und ich habe gerade eine Idee, in welche Richtung wir versuchen sollten, es zu lösen (so fand ich diese Frage).

Ich denke, das Problem mit der verknüpften Dokumentation wurde für falsch gehalten, als wir beschlossen, die Benutzerdokumentation in den Quellcode aufzunehmen. Wie Docco.

Lassen Sie uns zunächst Codekommentare von der Benutzerdokumentation unterscheiden.

Codekommentare sind normalerweise am besten, wenn sie kurz sind, in der Tat sehr kurz, sodass ich den Code, der das Zeug macht, tatsächlich lesen kann, ohne Gedichte darüber zu sehen, warum und wie es funktioniert.

Benutzerkommentare sind für Personen gedacht, die versuchen, Ihre Bibliothek / API zu verwenden. Sie können Anwendungsbeispiele, Erläuterungen zu deren Implementierung oder Anweisungen zum Erweitern der Bibliothek enthalten. Diese Art von Kommentaren ist in der Regel sehr ausführlich.

Ich bin damit einverstanden, dass die Dokumentation im Klartext verfasst sein sollte, damit sie nicht vom Hersteller festgelegt wird und einfach in ein VCS eingefügt werden kann. Ich denke jedoch, dass das Speichern der Benutzerdokumentation in der Quelldatei aus mindestens zwei Gründen ein großer Fehler war:

• Code schwerer zu lesen
• Die Dokumentation ist nicht flexibel genug (Angenommen, ich benötige zwei Dokumentationsseiten mit demselben Beispielcode oder eine Dokumentationsseite, auf der Code aus zwei verschiedenen Quelldateien verschachtelt werden muss).

Warum wollen wir es also in derselben Datei haben? Nun, niemand möchte, dass seine Dokumentationen nicht mit dem Code synchron sind. Aber wir machen es trotzdem und besonders jetzt ein Tag mit dem großen Erfolg von Markdown. Was ich denke, ist auf dem richtigen Weg, aber wenn es zu kurz kommt, warten Sie.

Wenn wir Codekommentare mit Benutzerkommentaren verschachteln, haben wir eine 2-Wege-Bindung. So können wir leicht erkennen, welcher Kommentar welchem ​​Teil des Codes entspricht. Wir können auch sehen, ob ein Code nicht dokumentiert ist. Was es nicht bietet, ist eine Möglichkeit zu sehen, ob der Kommentar aktualisiert wurde oder nicht, und das passiert häufig, wenn Ihr Code schwer zu lesen ist (weil die Dokumentation ihn hässlich gemacht hat).

Was ist, wenn wir anstelle einer 2-Wege-Bindung eine Einwegbindung haben? Dokumentation, die auf Code verweist. Wir könnten Markdown-Code mit speziellen Befehlen haben wie:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Dies hat den Vorteil, dass es sich bei einigen Ergänzungen um ein Markup handelt, und mit den richtigen Tools könnten wir mehr Wert hinzufügen.

Stellen Sie sich diese Einwegbindung mit Werkzeugen wie Grunzen vor (auch bei der Uhrenaufgabe). Sie können erkennen, wann sich eine Quelldatei ändert, sehen, welche Dokumentationsdateien davon abhängen, und den Benutzer warnen (oder irgendwo markieren), ob sich der kommentierte Code geändert hat.

404 Seite nicht gefunden

Wenn Sie mit Code arbeiten, möchten Sie nicht, dass Ihre Kommentare verloren gehen. Dies geschieht, wenn Sie Code und Kommentare in separate Dokumente trennen.

Wenn Sie die Versionierung zwischen Ihrem Kommentardokument und dem Codedokument beibehalten, werden Sie mehr Schmerzen haben als gewinnen.

Einige der Vorschläge, die Sie machen, gefallen mir sehr gut, könnten aber leicht umgesetzt werden, während Code und Kommentare in einer Datei enthalten sind.

Mögliche Nachteile, die ich sehe:

• Sie benötigen einen speziellen Editor, der diese Funktion implementiert

• Der Code ist nicht mehr nur einfacher Text, sondern einfach zu bearbeiten und in VCS-es festzuschreiben

• Sie benötigen zweimal mehr Bildschirmbreite, um mit dem Code arbeiten zu können

Wie für Ihre Argumente:

Mehr Quellcode und mehr Dokumentation auf den Bildschirmen gleichzeitig

Dies kann jedoch unpraktisch sein, wenn Sie zwei Dateien nebeneinander anzeigen möchten.

Möglichkeit, die Dokumentation unabhängig vom Quellcode zu bearbeiten (unabhängig von der Sprache?)

Ich würde argumentieren, dass es tatsächlich ein Nachteil ist. Ich persönlich versuche, die Dokumentation so nah wie möglich am Code zu halten, damit sie nicht veraltet ist.

Schreiben Sie Dokumentation und Quellcode parallel, ohne Konflikte zusammenzuführen

Auch hier möglicherweise ein Nachteil. Wie können Sie Ihre Dokumente unabhängig voneinander bearbeiten, wenn sie stark mit Code verschachtelt sind?

Hyperlink-Dokumentation in Echtzeit mit hervorragender Textformatierung

Wenn es im Code enthalten ist, ist es bereits in Echtzeit;) Bei den Hyperlinks ist das Springen zur Definition in den meisten IDEs bereits implementiert.

Quasi-Echtzeit-Maschinenübersetzung in verschiedene natürliche Sprachen

Ich verstehe nicht, warum Sie das nicht mit regulären Kommentaren / Dokumentzeichenfolgen tun können.

Jede Codezeile kann eindeutig mit einer Aufgabe, einer Geschäftsanforderung usw. verknüpft werden.

Ich bin mir nicht sicher ... Kann ich das nicht mit regelmäßigen Kommentaren erreichen?

Die Dokumentation kann automatisch einen Zeitstempel erstellen, wenn jede Codezeile geschrieben wird (Metriken).

Stellen VCS-es diese Art von Informationen nicht bereits zur Verfügung?

Trotzdem gefällt mir das Layout sehr gut - aber ich sehe keine Notwendigkeit, das Dateiformat zu ändern. Es ist nicht so schwierig, es aus regelmäßigen Kommentaren zu generieren. Es gibt eine Reihe von Dokumentationsgeneratoren, die dies tun, z. B. Docco und seine Nachfolger wie Pycco oder Marginalia .

Erstens müssen die Dokumentkommentare zum Code passen. Wenn Sie sie an einen anderen Ort verschieben, ist es unglaublich schwierig, die Dinge so zu handhaben, dass praktisch kein Gewinn erzielt wird. Wieso sich die Mühe machen!

Sie können diese eingebetteten Kommentare jedoch im Editor ausblenden und in einer Blase oder einem Tooltip anzeigen oder so weiter. Ich würde hoffen, dass ein solcher Ansatz die Leute dazu ermutigen könnte, viel mehr Dokumentation in den Code zu schreiben - z. B. könnte eine Beschreibung einer Klasse eher zur Klasse als in ein externes Designdokument passen.

Sie können derzeit Hyperlinks in Codekommentare einbetten und mit Tools wie Doxygen oder Sphinx Dokumente aus dem Code generieren. Ich denke, es würde nur eine ausgefallene Erweiterung des Code-Editors erfordern, um diese Tools besser zu unterstützen.

Ich würde keine Codezeilen mit einem Bug-Tracker oder einem Anforderungs-Tool verknüpfen. Das ist ein besserer Job für Ihr SCM. Anschließend können Sie Code-Änderungen pro Commit anzeigen, die mit einer Aufgabe verknüpft sind. Ich würde die im Code gespeicherte Dokumentation auch nicht gegen den Bug-Tracker integrieren - Sie wären verrückt, wenn Sie jemals auf eine neue migrieren wollten (hmm, ich kann sehen, dass diese Funktion jetzt zu TFS hinzugefügt wird) oder wenn Sie hat Ihren Commit-Verlauf verloren (was passiert)

Neben dem, was @Bogdan bereits sagt, möchte ich einige hinzufügen:

• Ich habe meine IDE so konfiguriert, dass immer 2 Dateien gleichzeitig vorhanden sind. Mit der von Ihnen vorgeschlagenen Funktion würde ich grundsätzlich 2 Monitore benötigen, um die gleiche Menge an Informationen zu sehen, und 3, um das zu tun, was ich jetzt mit 2 mache.
• Beim Durchsuchen einer Datei werden die Kommentare nicht sofort angezeigt. Wenn Sie nicht genau wissen, wonach Sie suchen, ist es sehr schwierig, sie zu finden.
• Beim Durchsuchen einer Datei kann ich Kommentare nicht direkt (oder so einfach) durchsuchen.
• Ich muss manchmal verschiedene Tests durchführen / kurze Codeteile über ssh auf den Live-Server schreiben . Obwohl die von Ihnen angegebene Funktionalität in VIM oder andere Befehlszeileneditoren integriert werden könnte, würde es höchstwahrscheinlich ziemlich große Probleme geben

• Die meisten IDEs unterstützen das Reduzieren von Code / Kommentaren , wobei die Endergebnisse die folgenden sind:

  Anstelle des Normalen:

  

Machen Sie den Code besser lesbar, falls Sie die Kommentare nicht benötigen.

Quellcode und Dokumentation so, wie es gemacht werden sollte.

http://jasmine.github.io/2.3/introduction.html