Kommentieren Sie den Quellcode mit Diagrammen als Kommentare

14

Ich schreibe viel (hauptsächlich C ++ und Javascript) Code, der sich mit rechnergestützter Geometrie und Grafiken sowie solchen Themen befasst. Daher habe ich festgestellt, dass visuelle Diagramme ein unverzichtbarer Bestandteil des Prozesses zur Lösung von Problemen sind.

Ich habe gerade festgestellt, dass "oh, wäre es nicht fantastisch, wenn ich ein handgezeichnetes Diagramm als Kommentar an ein Stück Code anhängen könnte ", und dies würde es mir ermöglichen, auf etwas zurückzukommen, an dem ich gearbeitet habe. tage, wochen, monate früher und weitaus schneller re-grok meine algorithmen.

Als visueller Lerner habe ich das Gefühl, dass dies das Potenzial hat, meine Produktivität bei nahezu jeder Art von Programmierung zu verbessern, da einfache Diagramme zum Verständnis und zum Nachdenken über jede Art von nicht trivialer Datenstruktur beitragen können. Diagramme zum Beispiel. Während des Graphentheorieunterrichts an der Universität konnte ich nur die Graphenzusammenhänge wirklich nachvollziehen, von denen ich tatsächlich grafische Darstellungen zeichnen konnte.

So...

Meines Wissens nach können Sie mit keiner IDE ein Bild als Kommentar zum Code speichern.

Ich war der Meinung, dass ich oder jemand anderes ein relativ benutzerfreundliches Tool finden könnte, das ein Bild in eine base64-Binärzeichenfolge konvertieren kann, die ich dann in meinen Code einfügen kann.

Wenn der Konvertierungs- / Einfügeprozess ausreichend optimiert werden kann, kann eine weitaus bessere Verbindung zwischen dem Diagramm und dem tatsächlichen Code hergestellt werden, sodass ich meine Notizbücher nicht mehr chronografisch durchsuchen muss. Noch großartiger: Plugins für die IDEs zum automatischen Parsen und Anzeigen des Bildes. Daran ist theoretisch absolut nichts Schwieriges.

Ich nehme an, dass es etwas länger dauern würde, bis ich herausgefunden habe, wie ich meine bevorzugten IDEs erweitern und diese Plugins warten kann. Daher wäre ich mit einer Art Code-Postprozessor sehr zufrieden, der das gleiche Auslesen und Auslesen durchführen würde rendern Sie die Bilder und zeigen Sie sie neben dem Code, in einem Browser oder so. Da ich ein Javascript-Programmierer von Beruf bin.

Was denken die Leute? Würde jemand dafür bezahlen? Ich würde. Aber ich möchte vielleicht auch darauf hinweisen, dass unabhängig davon, ob ich oder eine bedeutende Anzahl meiner Kollegen für so etwas bezahlen würde, der einzige Weg, wie so etwas gelingen könnte, eine Open-Source-Veröffentlichung wäre.

Steven Lu
quelle
4
Eine Alternative: Kommentieren Sie einen Link zu einer lokalen Bilddatei, die im Standardbildbetrachter geöffnet wird.
Hand-E-Food
Meine größte Angst wäre der Missbrauch des Systems. Sicher, es beginnt mit einem Diagramm, das für einen komplexen Algorithmus von Bedeutung ist, aber wie lange dauert es, bis jemand fadenscheinige Spezifikationsdokumente in die Kommentare für die Klasse hochlädt? Bevor Sie es wissen, wird alles, was mit dem Projekt und dem Entwickler zu tun hat, in Codekommentare eingebettet. Natürlich ist jedes mächtige System für Missbrauch offen. Ich denke, die Notwendigkeit ist eine Nische, aber wenn Sie in dieser Nische sind, wäre es ein sehr nützliches Werkzeug.
Snixtor
@ Hand-E-Food Schön! Eine Datei-URL in einem Kommentar wird standardmäßig als anklickbarer Link in Xcode angezeigt. Meine einzige Beschwerde dabei ist, dass es unmöglich zu sein scheint, eine URL für eine Datei mit relativem Pfad zu erstellen, sodass der anklickbare Linkaspekt (aller Wahrscheinlichkeit nach) beim Systemwechsel unterbrochen wird.
Steven Lu
Sie könnten interessiert sein an ASCII ungerichteten Graphen oder Bäumen
TehShrike
Ich mache Javadoc, das HMTL erzeugt, mit Bildern. Oder SimpleDocBook, separate Dokumentation, XML-basiert, auf die im Code für Geschäftsregeln verwiesen werden kann / muss. Das liefert nette Prosa und deckt das System aus der Perspektive der gesamten Geschäftslogik ab, anstatt von Softwarekomponenten und Schichten (Klassen) verteilt zu werden. Bei jeder Änderungsanforderung wird ein Code mit als Verweis auf das Docbook + Version / Ticketnummer hinzugefügt, und das Docbook enthält eine Liste der Änderungen + Ticketnummer. Das funktioniert aufgrund seiner vollständigen Abdeckung. Ich bin mir nicht sicher, wie es zu deiner Situation passen würde.
Joop Eggen

Antworten:

6

Was ist mit Image Insertion Plugin für Visual Studio ?

Wenn Sie eine andere IDE verwenden und entweder keine eingebetteten Images unterstützen oder keine Zeit zum Erweitern haben, können Sie einen Link zu einem Image in den Kommentaren einfügen, während sich das Image an einer beliebigen Stelle im Repository befindet ?

Arseni Mourzenko
quelle
Das ist ziemlich toll. Ich benutze VS bei der Arbeit, damit ich das ausprobieren kann! Vielen Dank. Das Bild im Repo zu speichern und es irgendwie zu verknüpfen, ist definitiv eine Möglichkeit, dies zu erreichen, aber ich bin mir ziemlich sicher, dass es immer noch zu viel Buchhaltungsarbeit ist, als dass ich es zuverlässig implementieren könnte. Ich bin ein ziemlich fauler Programmierer.
Steven Lu
Das Speichern der Bilder im Repo funktioniert auch mit den meisten Repo-Browsing-Methoden (z. B. VCS-Repo-Weboberfläche)
Steven Lu,
4

Wenn Sie kein ASCII-Zeichner sind , können Sie doxygen zusammen mit dot / graphviz als Dokumentationswerkzeug verwenden .

Auf diese Weise können Sie eine Textbeschreibung von Diagrammen erstellen und in der Dokumentation wiedergeben.

Zum Beispiel diese Beschreibung:

digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

Rendert als:

Bildbeschreibung hier eingeben

mouviciel
quelle
Das ist cool! Unterstützung von Tools für Java-Umgebungen? Ich kann in diesem Mojo keine Unterstützung dafür finden, zum Beispiel: graphviz-maven-plugin.bryon.us/dot-mojo.html . Alle anderen haben eben auch Unterstützung für .dot-Dateien.
Oligofren
2

Sie können den emacs artist mode ausprobieren. Es würde eher Kunst als Bilder per se machen, also kann es sein, dass es nicht das ist, wonach Sie suchen. Insbesondere, wenn Ihre IDE keine Schriften mit fester Breite verwendet, wäre dies nicht sinnvoll. Als reiner Text würde es sehr gut mit der Versionskontrolle spielen.

Hier wird ein Screencast des Künstlermodus verwendet, damit Sie eine Vorstellung davon bekommen, ob Sie interessiert sind oder nicht.

Um den Künstlermodus in Emacs zu starten, drücken Sie Alt-X, geben Sie artist-mode ein und drücken Sie die Eingabetaste. Die mittlere Maustaste ruft das Menü auf. Die Tastenkombinationen für Ausschneiden und Einfügen sind standardmäßig nicht die normalen Windows-Tastenkombinationen. Sie können jedoch den CUA-Modus aktivieren, um dies zu ändern.

Michael Shaw
quelle
Wow das ist ... beeindruckend. Ich habe tatsächlich ein paar Kommentare im ASCII-Diagrammstil in meinem Code. Es ist einfach zu zeitaufwändig. Ich möchte bessere Tools verwenden, da die Technologie bereits verfügbar ist. Früher habe ich manchmal Code in Vim geschrieben, aber welche Skripte für die Codebewusstsein waren mir im Vergleich zu echten IDEs nicht gelungen. Aber danke, dass du mir diese Technik der alten Schule gezeigt hast!
Steven Lu
Ein paar Jahre später habe ich ein paar Vim-Goodies gesammelt, um die schnelle Zusammenstellung von Boxdiagrammen zu erleichtern. Egal, ob es sich um ASCII- oder Unicode-Zeichen handelt, dies ist eine sehr coole Art, Code mit coolen und nützlichen Kommentaren zu versehen. Vim kommt jedoch nicht mit etwas aus der Box.
Steven Lu
1

Was denken die Leute? Würde jemand dafür bezahlen? Ich würde.

ZOMG, ich gehöre zu einer ähnlichen Kategorie wie Sie und würde ein solches Feature direkt in der IDE lieben.

Im Moment tendiere ich einfach dazu, viele ASCII "Kunst" wie folgt zu machen:

// ******************************************************
// *v3            |e5          v4*           |e6      v6*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p1        *
// *              |            e1*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *cen           |p0          v0*           |        v5*
// *--------------~--------------************************
// *e4            |              *           |e7        *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p2        *
// *              |            e2*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *v2            |e3          v1*           |e8      v7*
// ******************************************************

Der Hauptwert, den ich finde, sind die Variablennamen, die dem visuellen Diagramm entsprechen, insbesondere wenn wir komplexe Durchquerungen von Maschen und dergleichen für neue Maschenalgorithmen verwenden. Dieser Trick zur Generierung von Sauerstoffgraphen, der in einer der Antworten gezeigt wird, ist super cool - ich sollte das mehr versuchen.

Es gibt so viele Dinge, die auch visuell einfacher zu kommunizieren sind, nicht unbedingt sogar mithilfe von Diagrammen. Beispiel:

Bildbeschreibung hier eingeben

... oder dies (Vergleich meines Algorithmus, den ich als "Hook-Unterteilung" mit der von Pixar verwendeten Standard-CC-Unterteilung bezeichne):

Bildbeschreibung hier eingeben

Es würde dem Code so viel Kontext geben, nur zu sehen, was diese Operationen bewirken und wie sie sich im Code unterscheiden, da einige Dinge einfach am besten visuell dargestellt werden. Bilder können wirklich tausend Worte fassen.

Daher wäre es für mich ein Traum, eine IDE zu haben, mit der ich Code und Bilder nebeneinander sehen und Bilder in den Quellcode einbetten kann.

Insbesondere wenn wir neue Algorithmen erfinden, ist es schwierig, sie sehr genau zu beschreiben (aus technischer Sicht, nicht aus Anwendersicht), ohne auf ihre algorithmischen Schritte einzugehen, da es nichts gibt, mit dem man sie wirklich direkt vergleichen kann. Diese Art von Vorher- und Nachher-Bildern zeigt in der Regel auf Anhieb, was Sie von dem Algorithmus erwarten können.

Eine andere Sache, von der ich träume, ist ein visueller Debugger, mit dem ich ihn so programmieren kann, dass einige meiner Datentypen ein Bild in den Debugger ausgeben, z. B. um die Ergebnisse visuell zu sehen, während ich durch den Code gehe und die Algorithmen überprüfe Ich versuche zu erfinden, dass bei jedem Schritt alles richtig funktioniert und wie ich es auf Papier geschrieben habe. Lassen Sie zum Beispiel meine Netzdatenstruktur ein gerendertes Bild im Überwachungsfenster des Debuggers ausgeben - ideal, wenn ich die Ansicht und dergleichen sogar gleich hier und da drehen könnte.

Auch wenn Sie in sehr großen Codebasen (zig Millionen von LOCs) arbeiten, die von losen Teams mit Tausenden von Plugins geschrieben wurden, kann es manchmal ein Albtraum sein, nur um herauszufinden, wie der Code ausgeführt werden soll, auf den wir schauen. selten benutztes Plugin von der Benutzeroberfläche. In solchen Fällen wäre es fantastisch, wenn der Code einen Miniatur-Screenshot enthalten könnte, der zeigt, wie dieser Code tatsächlich über die Benutzeroberfläche aufgerufen werden kann (dies kann dazu führen, dass die Benutzeroberfläche von Zeit zu Zeit veraltet ist, aber in der Regel sind die Benutzeroberflächen nicht so instabil Versionen, um frühere Screenshots unbrauchbar zu machen).

Würde jemand dafür bezahlen? Ich würde.

Also trotzdem, ja, total! Ich will das!!!


quelle
1
Tolle Bilder und vielen Dank für das Schreiben (obwohl es wahrscheinlich eher ein Kommentar als eine Antwort ist)! Ich habe vor kurzem beschlossen, eine Pause von coolen Grafiken und Simulationen einzulegen und Tools für das Debuggen und Tracen der nächsten Generation zu entwickeln . Wovon Sie träumen, ist den Dingen, von denen ich träume, sehr ähnlich.
Steven Lu
1
@StevenLu Ich habe oft davon geträumt, diese Art von IDE, die Sie vorschlagen, mit dem visuellen Debugger zu erstellen (obwohl ich darüber nachgedacht habe, es von Grund auf zu tun, da ich mir keine Plugin-Lösung vorstellen konnte, die die Debugger-Seite so gut macht). Aber ja - ich denke, diese Antwort war eine Art Kommentar ... aber ich war einfach so froh zu sehen, dass sich jemand anderes das wünschte. Meine Kollegen in der Vergangenheit waren eher technisch und mathematisch orientiert - sie haben meinen Wunsch, alles visuell zu kommunizieren, nicht ganz verstanden.
1
Vielleicht ist eine pseudowissenschaftliche Sichtweise, dass das visuelle System bei weitem die Schnittstelle mit der höchsten Bandbreite ist, die wir als Menschen haben, und obwohl es schade ist, dass wir es nur zur Verwendung als Eingabe zur Verfügung haben, ist die tiefe Integration des visuellen Systems in Der Gehirnspeicherzugriff ermöglicht visuellen Formaten einen eindeutigen Vorteil für die Dokumentation und die Verbreitung abstrakter Konzepte. ... Zu diesem Zweck arbeite ich an einem IDE-agnostischen Tool (gemäß der Unix-Philosophie), mit dem kompilierte Anwendungen automatisch strukturierte visuelle Darstellungen ihrer Interna generieren können, damit wir sie verstehen können.
Steven Lu
0

Klingt nach einem Anwendungsfall für die literarische Programmierung, bei dem Sie Ihrer Dokumentation Diagramme und Ähnliches hinzufügen können.

Wiedereinsetzung von Monica - M. Schröder
quelle
Warum die Gegenstimme?
Wiedereinsetzung von Monica - M. Schröder
Ich habe dich beleidigt. Es ist eine sehr gute Beobachtung, worüber ich fast ausschließlich spreche.
Steven Lu
1
Ich habe auch abgelehnt, weil dies nicht wirklich eine Antwort liefert. Er möchte ganz klar nicht sein gesamtes Programm auf einen Programmierstil mit Lese- und Schreibkenntnissen umstellen, und selbst wenn er dies getan hat, ist das Programmieren mit Lese- und Schreibkenntnissen nur ein Ansatz zum Programmieren - es bedeutet nicht unbedingt, dass Diagramme und Bilder unterstützt werden.
Timmmm
0

Mit Doxygen können Sie Bilder in Kommentare wie diesen einfügen :

  /*! Here is a snapshot of my new application:
   *  \image html application.jpg
   */

Leider scheinen keine IDEs diese Bilder inline anzuzeigen, aber ich vermute, es wäre nicht zu schwierig, eine VSCode-Erweiterung zu schreiben, um dies beispielsweise zu tun.

Ich fand auch eine VSCode Erweiterung , die dies bereits mit einer anderen Syntax unterstützen commentimg . Dies geschieht über einen Schwebeflug:

VSCode fügt eine Funktion hinzu, die Inline-Bilder ermöglicht - "Code-Einfügung" -, die jedoch noch nicht fertig zu sein scheint.

Hier ist ein Screenshot der Beispielerweiterung (den ich nicht finden konnte - vermutlich noch nicht veröffentlicht, da die Code-Inset-API noch nicht veröffentlicht wurde)

Timmmm
quelle