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.


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.

  • 4
    An alternative: Comment in a link to a local image file that opens in the default image viewer. – Hand-E-Food Nov 19 '12 at 0:28
  • My biggest fear would be abuse of the system. Sure it starts with a diagram meaningful to a complex algorithm, but how long until somebody is uploading flimsy specification documents into the comments for the class? Before you know it, everything project + developer related is blobbed into code comments. Of course, any powerful system is open to abuse. I think the need is a niche, but if you're in that niche it would be a very useful tool. – Snixtor Nov 19 '12 at 0:40
  • @Hand-E-Food Nice! A file URL in a comment shows up as a clickable link in Xcode out of the box. My only complaint with this is that it seems impossible to create a relative-path file URL, so the clickable link aspect breaks (in all likelihood) when switching systems. – Steven Lu Nov 19 '12 at 3:48
  • You may be interested in ascii undirected graphs or trees – TehShrike Nov 19 '12 at 11:46
  • I do javadoc which will generate HMTL, with images. Or SimpleDocBook, separate documentation, XML based, one can/must reference to in the code for business rules. That delivers nice prose, and covers the system out of the perspective of all business logic, instead of distributed of software components and layers (classes). Every change request, adds code with with as reference to the docbook+version/ticket number, and the docbook has a list of changes+ticket number. That works because of its complete coverage. Not sure how it would suit your situation. – Joop Eggen Apr 30 '19 at 10:38

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?

| improve this answer | |
  • That's pretty cool. I do use VS at work so I might try that out! Thanks. Saving the image into the repo and somehow linking it is definitely one way to accomplish this but I am pretty sure it's still too much bookkeeping work for me to reliably implement. I'm a pretty lazy programmer. – Steven Lu Nov 18 '12 at 23:47
  • Saving the pictures into the repo would also work with most methods of repo-browsing (e.g. VCS repo web interface) – Steven Lu Nov 19 '12 at 0:11

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 {
    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:

enter image description here

| improve this answer | |
  • That is cool! Any tool support for Java environments? I cannot see anything resembling support for this in this Mojo for instance: graphviz-maven-plugin.bryon.us/dot-mojo.html. All other have also just had support for .dot files. – oligofren Nov 19 '12 at 13:50

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.

| improve this answer | |
  • Wow that's... impressive. I actually have a few ASCII diagram style comments in my code. It's just too time consuming. I'm gonna want to use better tools because the technology is already here. I used to write code in Vim sometimes but what code-awareness scripts I had fell short compared to real IDEs. But thanks for showing me this old school technique! – Steven Lu Nov 19 '12 at 3:34
  • Visiting a few years later and I've since collected a few Vim goodies to aid in quickly assembling box diagrams. whether it is ascii or unicode box characters, this is a very cool way to embellish some code with cool and useful comments. Vim doesn't come with any of it out of the box however. – Steven Lu Jan 4 '16 at 18:40

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:

enter image description here

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

enter image description here

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

| improve this answer | |
  • 1
    Awesome pictures and thanks for the writeup (even though its probably more of a comment than an answer)! I've decided recently to completely take a break from cool graphics and simulation stuff and build next-gen debugging and tracing tools. What you dream about are very similar to the things I dream about.... – Steven Lu Jan 4 '16 at 17:54
  • 1
    @StevenLu I've dreamt often of making this kind of IDE you're proposing with the visual debugger (though I was thinking of doing it from ground up since I couldn't imagine a plugin solution doing the debugger side so well). But yeah -- I guess that answer was kind of a comment... but I was just so happy to see someone else wishing for that. My co-workers in the past were more techie and mathematical types -- they didn't quite understand my desire to communicate everything visually. – user204677 Jan 4 '16 at 17:59
  • 1
    Perhaps one pseudo-scientific way to look at it is that the visual system is far and away the highest bandwidth interface we have as humans, and although it sucks that we only have it available for use as an input, the visual system's deep integration into brain memory access allows visual formats an unequivocal advantage for documentation and the dissemination of abstract concepts. ... To that end, I'm working on an IDE-agnostic tool (following the Unix philosophy) which allows compiled applications to auto-generate structured visual representations of its internals so we can understand them. – Steven Lu Jan 4 '16 at 18:36

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)

| improve this answer | |

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

| improve this answer | |
  • Why the downvote? – Martin Schröder Feb 11 '14 at 11:46
  • I upvoted you. It's a very good observation, what I am discussing almost entirely falls under that umbrella. – Steven Lu Jan 4 '16 at 18:28
  • 1
    I downvoted too because this doesn't really provide an answer. He clearly doesn't want to switch his entire program to a literate programming style, and even if he did, literate programming is just an approach to programming - it doesn't necessarily mean that diagrams and pictures are supported. – Timmmm Apr 30 '19 at 9:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.