Explaining Code Using ASCII Art(blog.regehr.org)

blog.regehr.org

https://blog.regehr.org/archives/1653

48 comments

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]

[0] https://github.com/sourcegraph/sourcegraph/blob/2.13.0/doc/d... [1] https://github.com/sourcegraph/sourcegraph/blob/master/doc/d...

sqs7년 전

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.

Note: For anyone else interested, you can read the architecture doc mentioned in the parent comment at https://docs.sourcegraph.com/dev/architecture.

BTW, it would be awesome for someone to build a Sourcegraph extension (https://docs.sourcegraph.com/extensions) that renders Mermaid/Graphviz diagrams in code. Then you could see the rendered graphs when browsing on GitHub if you use our Chrome/Firefox browser extensions (https://docs.sourcegraph.com/integration/browser_extension).

KayEss7년 전

We're experimenting with Mermaid diagrams <https://mermaidjs.github.io/> in our source code. How does that come across?

miki1232117년 전

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.

brbrodude7년 전

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:

edit.: No way I can make it keep format here lol https://github.com/salgadobreno/dme/blob/master/README.md

pdsouza7년 전

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.

[0] https://preetam.io/post/s3-static-hosting-https/

[1] https://metacpan.org/pod/distribution/App-Asciio/lib/App/Asc...

wodny7년 전

asciio is great, I use it a lot to document architecture of systems.

euske7년 전

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.

rubenbe7년 전

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.

robin_reala7년 전

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.

HocusLocus7년 전

I've actually used that dBASE diagram to write my own parser,

http://www.dbfree.org/webdocs/1-documentation/0018-developer...

blast from the past!

netsec_burn7년 전

This is why I use TempleOS. Graphics inline in my Holy C.

wernsey7년 전

I've used asciidraw.com [1] in the past for diagrams like these. I like its simplicity.

Then for fun, if you have to email the diagram, use the shaky tool [2] to convert it to an image.

[1] http://www.asciidraw.com/#Draw [2] http://shaky.github.bushong.net/

purplezooey7년 전

I'd really like some c/c++ code that nicely prints trees in ascii... never found a good one

batat7년 전

Not that easy to keep these kind of "docstrings" up to date though.

Cub37년 전

I do this with Monodraw all the time mainly so I can add to markdown files

userbinator7년 전

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.

raymondh7년 전

These examples were nicely curated. Thank you.

rb8087년 전

btw http://asciiflow.com/ is great for doing ascii diagrams like these.

ktpsns7년 전

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.

pgeorgi7년 전

I started to use ditaa (http://ditaa.sourceforge.net/) to render inline ascii art diagrams into something "pretty".

asciidoctor supports that (and lots of other specialized diagram tools) with little effort (https://asciidoctor.org/docs/asciidoctor-diagram/)

emp7년 전

There is plantUML. Then diagrams can live alongside source code and be under version control.

zokier7년 전

Found this which looks pretty neat https://github.com/jbn/IPlantUML

guessmyname7년 전

I have been doing this for years, my favorite tool is Monodraw [1].

It’s unfortunate they decided to discontinue its development [2].

[1] https://monodraw.helftone.com/

[2] https://blog.helftone.com/monodraw-maintenance-mode/

dogecoinbase7년 전

Darn, I missed that Monodraw was maintenance-only. I use it at least once a week if not more frequently.

Sendotsh7년 전

That looks amazing. Does anyone have an equivalent for Windows or Ubuntu/Mint?

brbrodude7년 전

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).

A little one I done with it: https://github.com/salgadobreno/dme/blob/master/README.md

Abusing unicode chars, I've done some pretty interesting mock-ups...

guessmyname7년 전

According to AlternativeTo [1] there are two software for Windows with similar features [2][3].

[1] https://alternativeto.net/software/monodraw/?platform=window...

[2] http://www.torchsoft.com/en/aas_information.html

[3] http://www.jave.de/

brianpgordon7년 전

It's still worth buying! It's got a dizzying amount of functionality, and the app is beautiful. Highly recommended.

ginko7년 전

Users of Emacs can use artist-mode to do this in their code at any time.

brbrodude7년 전

And DrawIt for Vim

falcrist7년 전

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.

hk__27년 전

There’s some irony in presenting these pieces of ASCII Art (i.e. text) as PNG/JPG images.

waynecochran7년 전

A little ASCII art for math from a code snippet of mine:

    //                                                                  
    // B(m,n)(x) = binomial(m,n) * (1-x)^(m-n) * x^n                         
    //               __ m-n                                                  
    // (1-x)^(m-n) = \      (-1)^i * binomial(m-n,i) * x^i                   
    //               /_ i=0                                                  
    //                           __ m-n                                      
    // B(m,n)(x) = binomial(m,n) \      (-1)^i * binomial(m-n,i) * x^(i+n)   
    //                           /_ i=0                                      
    //                                                                       
    Polynomial Polynomial::bernstein(unsigned m, unsigned n) {
       Polynomial B(m);
       unsigned j = m-n;
       double scale = binomial(m,n);
       for (unsigned i = 0; i <= j; i++)
          if (isEven(i))
             B[i+n] = scale*binomial(j,i);
           else
             B[i+n] = -scale*binomial(j,i);
        return B;
      }

sn417년 전

Maxima[1] can do symbolic computation and display the result in ASCII. I use Maxima notation when I need to do this.

[1] https://en.wikipedia.org/wiki/Maxima_(software)

AnaniasAnanas7년 전

I just use latex for things like that in my comments.

weinzierl7년 전

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].

[1] https://www.w3.org/TR/WCAG20-TECHS/F72.html

josephg7년 전

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.

gbear6057년 전

If a tool is 90% good and 10% bad, it still makes my work better despite the presence of the bad

makapuf7년 전

Especially if those 10% can be ignored (document ahead when its useful but respect the guidelines in other aspects )

smlacy7년 전

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!)

https://pastebin.com/raw/Bg5L9ZJV

caf7년 전

HN supports some unicode in comments: いただきます

I'm not sure if it's a whitelist or a blacklist, but either way it's a deliberately curated subset.

Waterluvian7년 전

In my opinion ASCII art can make things look unnecessarily complex. Daunting.

KenanSulayman7년 전

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.

[1] https://monodraw.helftone.com

Example copied from a program that fetches data from somewhere and prepares it and mounts it as a fuse file system:

    /*
    ┌─────────────────────────────────────┐
    │                      ┌─────────────┐│
    │                      │             ││
    │      ┌──memory───◀───┼───┬──────┐  ││
    │      │main thread│   │   │parser│  ││
    │      └───────────┴───┼───▶──────┘  ││
    │          │ ▲         │     │ ▲     ││
    │          │ │         │     │ │     ││
    │          │ │         │     │ │     ││
    │          ▼─│         │     │ │     ││
    │         ;20s:        │     │ │     ││
    │         :   ;        │     │ │     ││
    │          ╲ ▲         │     ▼─│     ││
    │          │'│         └────;120s────┘│
    │┌─────────┼─┼────────┐ ┌──▶:   ;───┐ │
    ││    ┌────▼─┴────┐   │ │    ╲ ╱    │ │
    ││    │fast memory│   │ │     '     │ │
    ││    │main thread│   │ │     Λ     │ │
    ││    └─┬───────▲─┘   │ │    ╱ ╲    │ │
    ││      │       │     │ │   ╱   ╲   │ │
    ││    ┌─▼─fuse──┴─┐   │ └──     ◀─┘ │
    ││    │controller │   │    beacon     │
    ││    └─┬───────▲─┘   │      ╲ ╱      │
    ││      │       │     │       V       │
    │└──────┼───────┼─────┘               │
    │┌──────▼───────┴─────┐               │
    ││   fuse <> kernel   │               │
    │└────────────────────┘               │
    └─────────────────────────────────────┘
    */

(screenshot of comment without the HN formatting issues: https://i.imgur.com/YOaysWn.png)

lifthrasiir7년 전

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.

[1] https://www.unicode.org/reports/tr11/#Ambiguous

[deleted]7년 전

purplezooey7년 전

Mac only... no Linux... wtf

lincpa7년 전

Markdown Literary programming that don't break the syntax of any programming language

https://github.com/linpengcheng/PurefunctionPipelineDataflow...

advantages:

- 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.