Annotate source code with diagrams as comments

Question

I write a lot of (primarily c++ and javascript) code that touches upon computational geometry and graphics and those kinds of topics, so I have found that visual diagrams have been an indispensable part of the process of solving problems.

I have determined just now that "oh, wouldn't it just be fantastic if I could somehow attach a hand-drawn diagram to a piece of code as a comment", and this would allow me to come back to something I worked on, days, weeks, months earlier and far more quickly re-grok my algorithms.

As a visual learner, I feel like this has the potential to improve my productivity with almost every type of programming because simple diagrams can help with understanding and reasoning about any type of non-trivial data structure. Graphs for example. During graph theory class at university I had only ever been able to truly comprehend the graph relationships that I could actually draw diagrammatical representations of.

So...

No IDE to my knowledge lets you save a picture as a comment to code.

My thinking was that I or someone else could come up with some reasonably easy-to-use tool that can convert an image into a base64 binary string which I can then insert into my code.

If the conversion/insertion process can be streamlined enough it would allow a far better connection between the diagram and the actual code, so I no longer need to chronographically search through my notebooks. Even more awesome: plugins for the IDEs to automatically parse out and display the image. There is absolutely nothing difficult about this from a theoretical point of view.

My guess is that it would take some extra time for me to actually figure out how to extend my favorite IDEs and maintain these plugins, so I'd be totally happy with a sort of code post-processor which would do the same parsing out and rendering of the images and show them side by side with the code, inside of a browser or something. Since I'm a javascript programmer by trade.

What do people think? Would anyone pay for this? I would. But I would perhaps also point out that regardless of whether I or some significant number of my peers would pay for such a thing, the only way such a thing is likely to succeed would be through an open source release.

Answer 1

What about Image Insertion plugin for Visual Studio?

If you're using a different IDE and either it doesn't support embedded images or you don't have time to extend it, then what about putting a link to an image in the comments, while the image would reside somewhere in the repository?

Answer 2

If you are not an ASCII artist, you can use doxygen as documentation tool together with dot/graphviz integrated to it.

This allows for writing textual description of graphs and rendering them in documentation.

For instance, this 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)" ];
}

renders as:

Answer 3

You could try the emacs artist mode. It would do ascii art rather than images per se, so it may or may not be what you're looking for. In particular, if your IDE doesn't do fixed-width fonts, it wouldn't be useful. Being plain text, it would play very nicely with version control.

Here's a screencast of artist mode being used, so you can get an idea if you're interested or not.

To start up artist mode in emacs, do Alt-x, type artist-mode, and hit return. The middle mouse button brings up the menu. The keybindings for cut and paste aren't the normal windows ones by default, but you can turn on CUA mode to change that.

Answer 4

What do people think? Would anyone pay for this? I would.

ZOMG, I fit in a similar category as you and would love such a feature directly in the IDE.

For now I just tend to do lots of ASCII "art" like this:

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

The main value I find is seeing the variable names corresponding to the visual diagram, especially when we're using complex traversals of meshes and such for new mesh algorithms. This doxygen graph-generating trick shown in one of the answers is super cool -- I should try that more.

There are so many things that are easier to communicate visually as well, not necessarily even using graphs. Example:

... or this (comparison of my algorithm I'm calling "hook subdivision" to standard CC subdivision as used by Pixar):

It would give the code so much context to just see what these operations do and how they differ inside the code because some things are just best shown visually. Pictures really can capture a thousand words.

So it would be totally dreamy to me to have an IDE that let me see code and images side-by-side, allowing me to embed images into the source code.

Especially when we're inventing new algorithms, it's hard to find a good way to describe them very accurately (from a technical perspective, not exactly user perspective) without going into their algorithmic steps since there's nothing to really compare them to directly. These kinds of before and after images tend to totally show what you can expect from the algorithm right away.

Another thing I dream about is a visual debugger that lets me program it so that I can make some of my data types output an image into the debugger, e.g., to see the results visually as I'm stepping through code and making sure the algorithms I'm trying to invent are working correctly at every step and matching up how I drew it up on paper. For example, make my mesh data structure output a rendered image in the debugger watch window -- ideal if I could even rotate the view and such right then and there.

Also when working in very large-scale codebases (tens of millions of LOC) written by loose teams with like a thousand plugins, sometimes it can be a nightmare just to figure out how to execute the code we're looking at for some obscure, rarely-used plugin from the UI. It would be so awesome in those cases if the code could embed a miniature screenshot showing how to actually invoke that code from the user interface (might be prone to get out of date from time to time, but usually UIs aren't so unstable across versions as to render former screenshots useless).

Would anyone pay for this? I would.

So anyway, yeah, totally! I want that!!!

Answer 5

Doxygen allows you to insert images in comments like this:

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

Unfortunately it seems like no IDEs will display these images inline, but I suspect it wouldn't be too hard to write a VSCode extension to do it for example.

I did also find one VSCode extension that already support this with a different syntax commentimg. This does it via a hover:

VSCode are adding a feature that allows inline images - "code inset" - but it does not appear to be ready quite yet.

Here is a screenshot from the sample extension (which I couldn't actually find - presumably hasn't been released yet since the code inset API isn't released yet)

Answer 6

Sounds like a use-case for Literate Programming where you could add diagrams and whatever to your documentation.