Annoter le code source avec des diagrammes en tant que commentaires

J'écris beaucoup de code (principalement c ++ et javascript) qui touche à la géométrie et aux graphiques de calcul et à ce genre de sujets, j'ai donc constaté que les diagrammes visuels étaient une partie indispensable du processus de résolution des problèmes.

J'ai déterminé tout à l'heure que "oh, ne serait-il pas tout simplement fantastique de pouvoir en quelque sorte attacher un diagramme dessiné à la main à un morceau de code", et cela me permettrait de revenir à quelque chose sur lequel j'ai travaillé, des jours, des semaines, des mois plus tôt et beaucoup plus rapidement re-grok mes algorithmes.

En tant qu'apprenant visuel, j'ai l'impression que cela a le potentiel d'améliorer ma productivité avec presque tous les types de programmation, car de simples diagrammes peuvent aider à comprendre et à raisonner sur tout type de structure de données non triviale. Des graphiques par exemple. Pendant les cours de théorie des graphes à l'université, je n'avais pu que vraiment comprendre les relations entre les graphes dont je pouvais réellement dessiner des représentations schématiques.

Donc...

Aucun IDE à ma connaissance ne vous permet d'enregistrer une image en tant que commentaire à coder.

Ma pensée était que moi ou quelqu'un d'autre pouvions trouver un outil raisonnablement facile à utiliser qui puisse convertir une image en une chaîne binaire base64 que je pourrais ensuite insérer dans mon code.

Si le processus de conversion / insertion peut être suffisamment rationalisé, cela permettrait une meilleure connexion entre le diagramme et le code réel, donc je n'ai plus besoin de rechercher chronologiquement dans mes blocs-notes. Encore plus génial: des plugins pour les IDE pour analyser et afficher automatiquement l'image. Il n'y a absolument rien de difficile à cela d'un point de vue théorique.

Je suppose que cela me prendrait un peu plus de temps pour comprendre comment étendre mes IDE préférés et maintenir ces plugins, donc je serais totalement satisfait d'une sorte de post-processeur de code qui ferait la même analyse et le rendu des images et les montrer côte à côte avec le code, à l'intérieur d'un navigateur ou quelque chose. Depuis que je suis un programmeur javascript par métier.

Que pensent les gens? Est-ce que quelqu'un paierait cela? Je voudrais. Mais je voudrais peut-être aussi souligner que, que moi ou un nombre important de mes pairs paierais pour une telle chose, la seule façon de réussir une telle chose serait par le biais d'une version open source.

Qu'en est-il du plugin d'insertion d'image pour Visual Studio ?

Si vous utilisez un IDE différent et qu'il ne prend pas en charge les images intégrées ou que vous n'avez pas le temps de l'étendre, alors qu'en est-il de mettre un lien vers une image dans les commentaires, alors que l'image résiderait quelque part dans le référentiel ?

Si vous n'êtes pas un artiste ASCII , vous pouvez utiliser doxygen comme outil de documentation avec dot / graphviz intégré.

Cela permet d'écrire une description textuelle des graphiques et de les rendre dans la documentation.

Par exemple, cette description:

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)" ];
}

s'affiche comme:

Vous pouvez essayer le mode artiste emacs. Cela ferait de l'art ascii plutôt que des images en soi, donc cela peut ou non être ce que vous recherchez. En particulier, si votre IDE ne fait pas de polices à largeur fixe, cela ne serait pas utile. Étant du texte brut, il jouerait très bien avec le contrôle de version.

Voici une capture d' écran du mode artiste utilisé, afin que vous puissiez vous faire une idée si vous êtes intéressé ou non.

Pour démarrer le mode artiste dans emacs, faites Alt-x, tapez artist-mode et appuyez sur Entrée. Le bouton central de la souris fait apparaître le menu. Les raccourcis clavier pour couper et coller ne sont pas ceux de Windows normaux par défaut, mais vous pouvez activer le mode CUA pour changer cela.

Que pensent les gens? Est-ce que quelqu'un paierait cela? Je voudrais.

ZOMG, je rentre dans une catégorie similaire à la vôtre et j'aimerais une telle fonctionnalité directement dans l'IDE.

Pour l'instant, j'ai tendance à faire beaucoup "d'art" ASCII comme ceci:

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

La principale valeur que je trouve est de voir les noms de variables correspondant au diagramme visuel, en particulier lorsque nous utilisons des traversées complexes de maillages et autres pour de nouveaux algorithmes de maillage. Cette astuce génératrice de graphiques doxygen montrée dans l'une des réponses est super cool - je devrais essayer plus.

Il y a tellement de choses qui sont plus faciles à communiquer visuellement, pas nécessairement même à l'aide de graphiques. Exemple:

... ou ceci (comparaison de mon algorithme que j'appelle "subdivision du crochet" à la subdivision CC standard telle qu'utilisée par Pixar):

Cela donnerait au code tellement de contexte pour simplement voir ce que font ces opérations et comment elles diffèrent à l'intérieur du code, car certaines choses sont simplement mieux affichées visuellement. Les images peuvent vraiment capturer mille mots.

Il serait donc totalement rêveur d'avoir un IDE qui me permettrait de voir le code et les images côte à côte, ce qui me permettrait d'incorporer des images dans le code source.

Surtout lorsque nous inventons de nouveaux algorithmes, il est difficile de trouver un bon moyen de les décrire très précisément (d'un point de vue technique, pas exactement du point de vue de l'utilisateur) sans entrer dans leurs étapes algorithmiques car il n'y a rien à comparer vraiment directement. Ces types d'images avant et après ont tendance à montrer totalement ce que vous pouvez attendre de l'algorithme tout de suite.

Une autre chose dont je rêve est un débogueur visuel qui me permet de le programmer afin que je puisse faire en sorte que certains de mes types de données produisent une image dans le débogueur, par exemple, pour voir les résultats visuellement pendant que je parcours le code et que je m'assure que les algorithmes J'essaie d'inventer fonctionne correctement à chaque étape et correspond à la façon dont je l'ai rédigé sur papier. Par exemple, faire en sorte que ma structure de données de maillage génère une image rendue dans la fenêtre de surveillance du débogueur - idéal si je pouvais même faire pivoter la vue et ainsi de suite.

De plus, lorsque vous travaillez dans des bases de code à très grande échelle (des dizaines de millions de LOC) écrites par des équipes lâches avec un millier de plugins, cela peut parfois être un cauchemar juste pour comprendre comment exécuter le code que nous recherchons pour certains obscurs, plugin rarement utilisé de l'interface utilisateur. Ce serait tellement génial dans ces cas si le code pouvait incorporer une capture d'écran miniature montrant comment réellement invoquer ce code à partir de l'interface utilisateur (pourrait être sujet à être obsolète de temps en temps, mais généralement les interfaces utilisateur ne sont pas si instables à travers versions pour rendre les anciennes captures d'écran inutiles).

Est-ce que quelqu'un paierait cela? Je voudrais.

De toute façon, oui, totalement! Je veux cela!!!

Cela ressemble à un cas d'utilisation pour la programmation littéraire où vous pouvez ajouter des diagrammes et autres à votre documentation.

Doxygen vous permet d'insérer des images dans des commentaires comme celui-ci:

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

Malheureusement, il semble qu'aucun IDE n'affichera ces images en ligne, mais je pense qu'il ne serait pas trop difficile d'écrire une extension VSCode pour le faire par exemple.

J'ai également trouvé une extension VSCode qui la prend déjà en charge avec une syntaxe différente commentimg . Cela se fait via un survol:

VSCode ajoute une fonctionnalité qui permet des images en ligne - "encart de code" - mais il ne semble pas encore tout à fait prêt.

Voici une capture d'écran de l' extension exemple (que je n'ai pas pu trouver réellement - n'a probablement pas encore été publiée car l'API de l'encart de code n'est pas encore publiée)