I like doing things in plain text and I like ASCII art. However, this is tedious work, if you don't have the tooling to maintain these "diagrams", when things change.
The table of "The layout of a data structure in the Jikes RVM" for example. Imagine, if suddenly there was a new attribute in one of the tables, which has a longer name than any of the previously existing ones. Great fun to manually widen the whole thing. With multiple cursors easily possible, but even then it sucks and there are other scenarios, where it gets much worse.
In Org mode I could imagine managing such a table and then copying it back into the code comment. And maybe Emacs' ASCII art drawing mode (forgot its name) would help me with other shapes, but drawing something like an ERM or so is still tedious.
Maybe those ASCII art diagrams could be created, when the design is already finished.
I generate the ASCII graph and then paste it in the comments together with a link to the service. This way I can go back later and update it if needed:
For some reason the arrow ▶ is a double-width character on my PC so it breaks.
I'm using Noto Sans Mono as monospace font. Broken with Iosevka as well, works with Dejavu Sans Mono.
That said, it's pretty cool, bookmarked.
EDIT: weird now I'm looking at my comment from an iPhone and the arrow is rendered with the arrow emoji. Have I found an exploit to embed emojis in HN comments?!
▶ is not a box-drawing character like the rest, so most monospace fonts won’t support it, so it’ll be rendered in a different font with almost certainly different metrics, so in environments that follow text metrics rather than rigidly drawing on a grid, that arrow will ruin everything. The web is one such environment.
Interestingly, my browser's default monospace choice of Courier is only very slightly distorted by the arrowheads. Like at most 2 pixels off when looking at it at whatever size it is on the dot-to-ascii site. Switching to Menlo results in no distortion at all.
> EDIT: weird now I'm looking at my comment from an iPhone and the arrow is rendered with the arrow emoji. Have I found an exploit to embed emojis in HN comments?!
Apple emoji font, in addition to emojis, also includes other characters like numbers, arrows, and "trademark" (tm), "registered" (r), and "copyright" (c) symbols, so that's why.
There's this neat mac app Monodraw. It costs 10 bucks but worth every penny because it's like a vector editor for ascii. I've used it for all sorts of things and heartily recommend it to anyone that does textual charts, diagrams and such.
> I like doing things in plain text and I like ASCII art. However, this is tedious work, if you don't have the tooling to maintain these "diagrams", when things change.
Not having integrated built-in tools to properly maintain this type of representation is a missed opportunity.
IDEs went the copy/paste and word replace route, and the few diagram and table drawing tools in ASCII are often in separate applications, reducing their usefulness.
Maybe the universal solution to this is for the Unicode Consortium to dedicate a set of codepoints for encoding SVG or something similar.
Then the system text renderer can be responsible for drawing these diagrams, and they can be embedded anywhere in text.
It would also have the side benefit of letting people draw their own emojis, rather than waiting some time from months to never to have their suggestions included in the next Unicode release.
Leave plaintext to be as plain as possible. Emoji were already a bad compromise made to get Japanese encodings to sort-of work. Leave markup to general markup languages. Don't make unicode even more convoluted.
a descent editor would have multi-cursor, multi-line edits that could be also configured to do 'inserts' over appends.
So you'd use a mouse to "draw" a line (if it's horizontal or vertical), and it'd take only 4 "draw line" to make a box, and turn on 'insert' mode to type in the text inside the box.
Drawing diagonal lines is a bit more involved, but not too hard either. Adding a cell to an ascii table is also pretty easy using this same method.
However, it is preferable to have the diagram in svg tho. The svg file could even be separate from the comments, but just referenced.
If we're already assuming an IDE, how about one that expands images which are linked in comments? It'd have minimal friction if everyone else on the team uses the IDE, and if someone does not, they can open the link instead.
I cannot find any information about an IDE which does this.
What would be really cool is if you can cut-n-paste an existing diagram (possibly also with comment markers) and edit it. Then cutting-and-pasting it back into the source code.
When you draw 2 boxes and an arrow between them, then move a box, it does not stay connected to the arrow. I think that is an instant no-go for designing diagrams. Perhaps it can be used for converting to plain text diagram, but not for working on diagrams and changing stuff around a lot.
Personally, I tend to use simple diagrams to illustrate the basics. I try to keep them as small and minimal as possible. This way I can reduce the risk of excess work if something changes. If the case, that I want to illustrate, is too complex to fit into a small ASCII diagram, it most likely should be better modeled in a dedicated modeling tool (I use Sparx EA).
Also I think that modeling languages like Mermaid are a nice alternative for small to medium diagrams. But these wont work in code comments. But they can be fitted into a Markdown file.
The table of "The layout of a data structure in the Jikes RVM" for example. Imagine, if suddenly there was a new attribute in one of the tables, which has a longer name than any of the previously existing ones. Great fun to manually widen the whole thing. With multiple cursors easily possible, but even then it sucks and there are other scenarios, where it gets much worse.
In Org mode I could imagine managing such a table and then copying it back into the code comment. And maybe Emacs' ASCII art drawing mode (forgot its name) would help me with other shapes, but drawing something like an ERM or so is still tedious.
Maybe those ASCII art diagrams could be created, when the design is already finished.