Screen reader user here. Please don't do this. There are blind developers out there. Don't make their life hell. Often those diagrams are a good excuse not to write a good description of what the system really does. If you absolutely must, please ensure there's a text description that provides exactly as much info as the diagram (or more). If you can, use formats like graphvis and include the text the graphs were generated from, it's at least somewhat readable. The way sourcegraph[0] used to do this was IMO acceptable. They had a graph but if you wanted to, you could sort of figure out what the grah looks like by reading it's text. They also had a good description of what the system does directly below. sadly, They're a bit worse now, though the source is still available if you dig deep enough. [1]
Sourcegraph CEO here. Thank you for pointing out that the way we embed our architecture diagram was better before for screen reader users. Sorry for the regression. I filed an issue at https://github.com/sourcegraph/sourcegraph/issues/2355 for us to include a link to the diagram's Mermaid source definition so you don't need to dig around for it.
I assume that as a reader of the code, I can get to the code behind those diagrams, not just the images? If yes, I would call it acceptable. Not something I'd prefer personally, but that's a good trade off between actually making an illustration for the sigted and making something accessible to everyone. Accessibility must be taken into consideration, but it shouldn't dominate the software and make the experience worse for users who don't need it. I think you strike the balance here.
I haven't created much ASCII art in my own code yet, but I've been VERY grateful to others who included it in a few of the legacy projects I've dealt with in the past.
One project in particular was troubling. It was an industrial spray controller for vinyards and such. As is typical with these older products, the microcontroller that drove it was an 8051 (some SiLab part I think). Normally that wouldn't matter, but this project was written in assembly. Even worse, it was one big file (something like 17k lines).
All of the main variables we're statically allocated for easier ram usage and eeprom saving. There were deliberately few functions in the program (almost everything was in the main loop), due to stack size limitations (it was a 23 byte stack I believe). I don't think a single macro was used in the entire project. Basically this was a very old and very crusty project.
The comments were the only redeeming quality. Timing diagrams, menu layouts, waveforms, LCD illustrations, etc. There were whole PAGES of ASCII art, and it saved my butt. Thank you to whoever made the decision to properly comment that code. I owe you a few beers.
EDIT: That's also around the same time I started using VS Code, which was a huge help. It beats the heck out of whatever 1990s-looking IDE they had me using to debug the project. You don't realize how nice it is to have proper search functionality and the ability to open a file in multiple frames until you don't have it anymore.
I use DrawIt plugin in Vim... As much as that looks beautiful, why would you open a GUI window to draw plain text? No need(although of course it doesn't look as slick).
We sometimes use Monodraw [1] for that in our team and it really made a difference. It's always great to get a top-down perspective on the topology / architecture at the beginning of a complex program.
It is unfortunate that almost virtually all box drawing characters and geometric shapes are ambiguous in the Unicode East Asian Width standard [1], so they can't be reliably used even in the preformatted text. I tend to default to ASCII art for this reason.
I even had in mind writing a post about this... Diagrams in code have so much potential to explain things better, and taking this kind of thing OUT of the code always ruin it(I much prefer code w/ TODOs & comments all around than code that is just code with zero human context), maintaining a little explanatory diagram is so much easier than trying to have drawings elsewhere where they'll get outdated, I think it should be encouraged. As I mentioned in some replies here, as a Vim user is quite seamless to do this with DrawIt plugin, this is one I've done just for the hell of it:
Love ASCII art! I even use it on my blog [0]. I write all my posts in Markdown and it's pretty sweet to be able to see and edit diagrams in-line with the rest of the post.
I'm still looking for an ASCII art editor to make it more pleasant to draw though. So far, I like the default styles in Asciio [1] the best.
Since some of these examples seemed to be part of a documentation system such as Javadoc, Sphinx or Doxygen, I wonder wether the more complicated examples would not be better made as proper drawings. It may be nerdy to draw huge diagrams in the text editor, but they are error prone (sometimes due to bad visualization). Instead, with a proper UML diagram editor or with Inkscape, such diagrams are quickly exported to SVG/PDF standard and rendered as a nice picture within the given documentation system. Drawback: They are no more part of the source code.
I find this useful and wish it was used more, but I have to say that I've seen it discouraged in coding guidelines. Another thing is that ASCII drawings can be easily destroyed by the auto formatter.
I think ASCII drawings should be used as an aid but not as a replacement for a textual description. If you use ASCII art on a website W3C recommends providing a text alternative [1].
Why do you obey coding guidelines or autoformatters which stop you writing good, well documented code? If a tool makes your work worse, fix it or stop using it.
I always find a good ASCII art in code comments heartwarming because it shows that they're serious about explaining the code to its readers. In other words, they care about you.
I generate dot files (graphviz) based on code. It's an amazing tool, both for understanding how the code behaves and as a communication tool others.
The clear advantage is that the documentation is always up to date. Spend time once to develop your tool, generate your doc at any time you want with almost zero cost.
For a simple state machine sed/grep/awk magic is sufficient to generate a dot file.
For a more complex data processing graph, I use boost graph.
Some of those are not technically ASCII art so probably won't be so readable in some editors/fonts, but diagrams are certainly useful in source code --- as long as they are accurate. Otherwise the effort required to update it may mean it becomes inaccurate quickly. Many of the examples show something that is unlikely to change often if at all, which fits the use-case well.
It's even more fun (better?) to encode 1-bin images directly into source code using the Unicode block character set! You can get 4 pixels per character, and do "lossless" representation of simple binary images:
(UGH! HN doesn't seem to support unicode in comments!)
They can be really useful, but it’s worth bearing in mind that these are all inherently inaccessible to people browsing your source code using a screen reader of some other non-visual presentation mechanism. By all means include them if you want, but it’s also good to use them as an enhancement to your textual representation rather than the only source.
- It don't break the syntax of any programming language, you can compile directly. comment area markup method can be applied to any programming language and any markup (including Org,rst, asciidoc, etc.), which is the greatest advantage.
- you only need a single line of regular replacement preprocessing, then you can use any Markdown parse or converter.
- Support any code editor that supports Markdwon Live preview, allowing the source code of any programming language to become rich text in real time. In the code's comment area, You can use the markdown to draw flowcharts, tables, task lists, and display images on the live preview panel, enhance the readability of your code.
- If you extend the Markdwon tag, you can implement the eval code, print result, display data visualization and other instruction tags, to achieve live programming, live test.
the main purpose of the Code comment area markup method is to live Preview directly in the Code Editor Preview panel without exporting or any preprocessing.
I think:
- Literary Programming, Programming was the first, Literary was the second.
- The entire file is compliant with the programming language syntax and can be compiled directly.
- When writing (reading or refactoring) code files, I can modify and live preview directly in the editor without exporting or any preprocessing.
- Do not interfere with people who do not understand the markup language to read the code.
