I came across this paper when I looking at the website of Prof. Philip Guo. Prof. Guo is renowned in Computer Human Interaction (CHI) circles for his work on the pythontutor.com. His other papers are definitely worth checking out e.g. Ten Million Users and Ten Years Later: Python Tutor’s Design Guidelines for Building Scalable and Sustainable Research Software in Academia
In this lovely little paper, the authors look at the use of ASCII diagrams in source code, specifically in 4 projects - Linux (OS), LLVM (computer), Chromium (Browser) Tensorflow (ML).
TL; DR - The diagrams that they dug up from the codebases and the design space they synthesized from the ASCII diagrams can be found at https://asciidiagrams.github.io/. Also, know, that there are 428 ASCII diagrams in Chromium, 1386 in Linux, 220 in LLVM, and 122 in Tensorflow.
Abstract : Documentation in codebases facilitates knowledge transfer. But tools for programming are largely text-based, and so developers resort to creating ASCII diagrams—graphical artifacts approximated with text—to show visual ideas within their code. Despite real-world use, little is known about these diagrams. We interviewed nine authors of ASCII diagrams, learning why they use ASCII and what roles the diagrams play. We also compile and analyze a corpus of 507 ASCII diagrams from four open source projects, deriving a design space with seven dimensions that classify what these diagrams show, how they show it, and ways they connect to code. These investigations reveal that ASCII diagrams are professional artifacts used across many steps in the development lifecycle, diverse in role and content, and used because they visualize ideas within the variety of programming tools in use. Our findings highlight the importance of visualization within code and lay a foundation for future programming tools that tightly couple text and graphics.
The researchers asked three research questions
RQ1 Characteristics. What are the key characteristics of the media of ASCII diagrams?
RQ2 Roles. How are ASCII diagrams used in the software development workflow?
RQ3 Content. What do ASCII diagrams show and how do they show it?
The first author, leveraging their initial enthusiasm for this project, scrolled through the entirety of the four files and manually extracted the comments that resembled ASCII drawings, resulting in a selection of 2,162 ASCII diagrams.
P2 gladly paid $10 for Monodraw, a diagram editor specifically for ASCII. It allowed them to edit the diagram after-the-fact, provided they had saved the Monodraw file, which proved helpful in a codebase where many contributors were authoring these diagrams: “the best $10 I could ever spend was having Monodraw…if I want to like enlarge a box, I can enlarge a box, I can move things around…I usually keep the Monodraw files sitting around so that if someone’s gonna come along and ‘Oh I’m gonna have to update this diagram.”’
Ref https://monodraw.helftone.com/
As an alternative to ASCII, both P1 and P2 mentioned Mermaid [61], a simple textual language for describing and rendering diagrams. The popular code collaboration site GitHub renders Mermaid automatically, so P1 now uses it instead of ASCII art when writing README files. P2’s team also uses Mermaid regularly on GitHub, particularly for charts that are updated often, as updating ASCII is tedious. Nevertheless, P2 remarked that code diffs of Mermaid were hard to understand and P1 still used ASCII in tools that didn’t support Mermaid (e.g. terminals and text editors).
I’ve used mermaid a bunch of times, especially on GitHub as it now natively renders the mermaid diagrams, but like the quote above, it still needs to be rendered and the information isn’t as visual as an ASCII diagram.
a birdseye overview of how they used diagrams
(1) to reify offline work,
(2) to illustrate test cases,
(3) for code review and verification from colleagues, and to document both (4) for others and (5) themselves
Finally, here are a few diagrams from the https://asciidiagrams.github.io/ dataset that I find interesting
// Note that speech recognition is activated on VR UI thread. This means it
// usually involves 3 threads. In the simplest case, the thread communication
// looks like the following:
// VR UI thread Browser thread IO thread
// | | |
// |----ActivateVS----->| |
// | |------Start------> |
// | | |
// | |<-NotifyStateChange-|
// |<--OnSRStateChanged-| |
// | | |
// | |<--OnSpeechResult---|
// |<--OnSRStateChanged-| |
// | navigate |
// | | |
// VS = voice search, SR = speech recognition
from chromium
/*
* +------------+---------------------------------------------------+
* | PHASE | FIRMWARE STATUS TRANSITIONS |
* +============+===================================================+
* | | UNINITIALIZED |
* +------------+- / | \ -+
* | | DISABLED <--/ | \--> NOT_SUPPORTED |
* | init_early | V |
* | | SELECTED |
* +------------+- / | \ -+
* | | MISSING <--/ | \--> ERROR |
* | fetch | V |
* | | AVAILABLE |
* +------------+- | \ -+
* | | | \--> INIT FAIL |
* | init | V |
* | | /------> LOADABLE <----<-----------\ |
* +------------+- \ / \ \ \ -+
* | | LOAD FAIL <--< \--> TRANSFERRED \ |
* | upload | \ / \ / |
* | | \---------/ \--> RUNNING |
* +------------+---------------------------------------------------+
*/
from linux
// An irreducible SCC is one which has multiple "header" blocks, i.e., blocks
// with control-flow edges incident from outside the SCC. This pass converts a
// irreducible SCC into a natural loop by applying the following transformation:
//
// 1. Collect the set of headers H of the SCC.
// 2. Collect the set of predecessors P of these headers. These may be inside as
// well as outside the SCC.
// 3. Create block N and redirect every edge from set P to set H through N.
//
// This converts the SCC into a natural loop with N as the header: N is the only
// block with edges incident from outside the SCC, and all backedges in the SCC
// are incident on N, i.e., for every backedge, the head now dominates the tail.
//
// INPUT CFG: The blocks A and B form an irreducible loop with two headers.
//
// Entry
// / \
// v v
// A ----> B
// ^ /|
// `----' |
// v
// Exit
//
// OUTPUT CFG: Edges incident on A and B are now redirected through a
// new block N, forming a natural loop consisting of N, A and B.
//
// Entry
// |
// v
// .---> N <---.
// / / \ \
// | / \ |
// \ v v /
// `-- A B --'
// |
// v
// Exit
//
// The transformation is applied to every maximal SCC that is not already
// recognized as a loop. The pass operates on all maximal SCCs found in the
// function body outside of any loop, as well as those found inside each loop,
// including inside any newly created loops. This ensures that any SCC hidden
// inside a maximal SCC is also transformed.
from llvm
// Computes a dot product between "[M,K]{0,1} lhs" with a [K,1] vector (the
// layout of the vector does not matter). This implementation uses a tiling
// scheme to improve performance.
//
// We logically separate the LHS matrix into four segments:
//
// +----------------------+---+
// | | |
// | | |
// | A | B |
// | | |
// | | |
// | | |
// +----------------------+---+
// | C | D |
// +----------------------+---+
//
// where A is the largest submatrix of the LHS that can be evenly divided into
// tiles. For each tile in A, assuming tile_rows_ == tile_cols_ == 4, we have:
//
// +---+---+---+---+ +--+--+--+--+
// |M00|M10|M20|M30| |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
// |M01|M11|M21|M31| and |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
// |M02|M12|M22|M32| |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
// |M03|M13|M23|M33| |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
//
// (Legend: rows are horizontal and columns are vertical; and each column is one
// llvm::Value of a vector type)
//
// where:
//
// a. The left tile is from the column major left matrix.
// b. The right tile is an elementwise broadcast of a [V0, V1, V2, V3]
// vector loaded from the RHS vector.
//
// As we iterate through the column dimension, we compute the change to the
// result vector by an elementwise multiplication between the two tiles above
// followed by a reduction along the major dimension:
//
// +-----------------------------------+
// | M00*V0 + M10*V1 + M20*V2 + M30*V3 |
// +-----------------------------------+
// | M01*V0 + M11*V1 + M21*V2 + M31*V3 |
// Result[R:R+4] += +-----------------------------------+
// | M02*V0 + M12*V1 + M22*V2 + M32*V3 |
// +-----------------------------------+
// | M03*V0 + M13*V1 + M23*V2 + M33*V3 |
// +-----------------------------------+
//
// Where R is the starting row for the tile.
//
// We have an inner epilogue loop to deal with the "C" submatrix and an outer
// epilogue loop to deal with the B,D submatrix.
//
// TODO(sanjoy): We should investigate if using gather loads and scatter stores
// can be used here have the same inner loop for both column-major and row-major
// matrix-vector products.
from tensorflow