Monodraw

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 ?