Explaining Code using ASCII Art

People tend to be visual: we use pictures to understand problems. Mainstream programming languages, on the other hand, operate in an almost completely different kind of abstract space, leaving a big gap between programs and pictures. This piece is about pictures drawn using a text character set and then embedded in source code. I love these! The other day I asked around on Twitter for more examples and the responses far exceeded expectations (thanks everyone!). There are a ton of great examples in the thread; here I’ve categorized a few of them. Click on images go to the repositories.

Data Structures

One of the most common kinds of ASCII art in code is illustrating the shape of a data structure.

The example I started with comes from LLVM:

The layout of a data structure in the Jikes RVM:

A tree rotate in Musl:

Double-ended queue from the Rust library:

Swift compiler internals:

Malloc header layout:

State Machines

JavaScript profiling:

RPCs in Cloud Spanner:

I/O stream states:

Logical Structure in the Problem Domain

Control flow in an NWScript program being decompiled:

ECC internals:

Formatting numbers:

A quantum circuit:

Balancing memory management objectives in an OS kernel:

Subtyping relations (this is a very cool special case where the ASCII art is also code):

You should publish them, it’s a good way to store knowledge besides being therapeutic. I’d personally would love to see classic science books put in this format, Euclid’s Elements or Newton’s Opticks but don’t have the time to do the work. I think this and something like itty.bitty.sites could help ease access to information.

I’m a fan of ASCII art in source code but have always been bothered by the inconvenience of modifying the diagram. I recently decided to learn Javascript, so I wrote a tool which lets you draw line diagrams. The tool converts the diagram into ASCII, and appends a string representing the serialized, compressed version of the diagram. This lets you get recreate and modify the original line diagram–round-trip editing.