Explaining Code Using ASCII Art

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;
      }

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

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

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)

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

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

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

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

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

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

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

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

https://pastebin.com/raw/Bg5L9ZJV

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.

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!

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

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

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/

These examples were nicely curated. Thank you.

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

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

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

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.