Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
3  
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
add comment

4 Answers

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:

enter image description here

share|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
add comment

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

share|improve this answer
    
Why the downvote? –  Martin Schröder Feb 11 at 11:46
add comment

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.

share|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
add comment

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?

share|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
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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