Kommentieren Sie den Quellcode mit Diagrammen als Kommentare

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.

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 ?

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:

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.

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:

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

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!!!

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

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)