Annotate source code with diagrams as comments

code-reviewscommentsimage manipulationproductivityworkflows

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.

Best Answer

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?

Related Solutions

Best Practices – Writing Comments and Documentation

Names/documentation should tell you what you are doing.
Implementation should tell you how you are doing it.
Comments should tell you why you do it the way you do.

Design Documentation – Documenting Design Decisions in Code Comments

How can I best document a code design decision in my source code?

The answer depends on your understanding of »best« and »design decision«.

What design decision I document in code:

As with all comments, I like having not more comments than necessary to undestand what is going on in the code. When reading code, I expect that the code is written in a way that makes it obvious what is going on. Accordingly I document my code.

Contrieved example ahead:

def calculate_total_of_articles(articles):
...
   return total

In this context, it should be clear, what this code does; it calculates the total of a collection of articles. No further comment necessary.

Say there is a new business requirement, that makes deviating from what one might expect necessary - say: if article abcd is in the list, one is for free - I would document this deviation in code:

def calculate_total_of_articles(articles):
"""calculates the total, but according to business decision
   https://ourtrackerwahtever.com/issue1234
   one of abcd comes for free
   ...
"""

I explain

what is different
why it is different
where to find the details / reason for that decision

Another example: Say, you have to sort articles by name. And you decided to implement bubblesort instead of quicksort or some other algorithm, I would not document that in code. I expect, that code is written in the way it is for a reason. If I have doubts about the decision made or have a proposal for improvement, I ask the original author and come up with my proposal how to improve. I do not expect a comment like

I know bubblesort is ugly but in this very case it is the best solution

Usually the context should be clear why you did that.

Should I just add a massive comment at a point I feel is right? I see no advantage in that.

For me a source file is about instructions, which tell me what should be done or what is expected this code should be doing. The question of why is secondary for me: even if it is

voices in my head told me to write the code in this way

As I said above: of course exceptional expectations should be documented - but in a way, which doesn't impede reading flow. Reasons could be given elsewhere. And if the reader is interested, he might follow, but she/he should have to leave the context of reading code.

Or should I just create a separate file?

I struggle with that. What file could that be? You could do it in a documentation section. But on the other hand, as a developer I expect from a documentation, that it tells me how to achieve possible goals, how to use the code, but not a secret diary of why you did certain things.

The longer I think about, the more I come to the conclusion:

No. A separate file isn't a good place - as long as it comes alongside your code.

tl;dr

So where to document reasons/decisions?

Project Wiki
Project (Bug-)tracker
Project Page
Project Blog

These are the best, if you accept the premise of keeping your codebase free of things not related to understand the code and avoiding lengthy explanations.

Best Answer

Related Solutions

Best Practices – Writing Comments and Documentation

Design Documentation – Documenting Design Decisions in Code Comments

Related Topic