Sounds super interesting, where do you put these diagrams ?
It's an issue I'm seeing even for comments touching too much on algorithmic stuff. To take a somewhat common example, if you were dealing with a credit card payment flow, where would the explanation of how a transaction goes through a few states asynchronously, which all trigger a webhook callback ?
Obviously the people working on the code need to be aware of that, so documentation is somewhere needed. I've seen people put whole blocks in class headers, other sprinkle it all inside the code, personally I ended up moving it outside of the code. Where would you put it?
I personally just throw them at the top of my files as long block-comments, or sometimes inside/around very heavy functions. For example i often add little diagrams for when dealing with some bit-fiddly logic parts to easier visualize the bit-layouts.
But for architecture, either a whole text-file for it or at the top of the module
Thanks! Do you deal with the logic getting split/shared around the code ? For instance on the credit card example there will be probably be one central class (the transaction class?) but you'd need to know the whole logic in the card registration part or the webhooks as well. I guess you don't stick a diagram everywhere ?
On one hand, this could provide a lot of value as some things are just plain hard to explain using only words. On the other hand, aren't you worried about when someone else comes along and needs to update one of those comments? If they're not aware of this tool, it's either going to be incredibly tedious or simply not going to happen.
As the other commenters put it, i dont think this is a huge issue.
I usually use this for architecture level diagrams, and that shouldn't change often/at-all. In-case it does change, doing a new diagram is perfectly in-scope of whoevers working on that.
Looks like Monodraw a mac only BTW. That should be fine if macs are mandatory for all the devs on a project, but it would otherwise create a kinda weird situation.
the fact i can export to clipboard and re-import it and reconstruct all the shapes etc. almost flawlessly is such a big win.