
Explaining Code Using ASCII Art - dmit
https://blog.regehr.org/archives/1653
======
waynecochran
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;
          }

~~~
sn41
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)](https://en.wikipedia.org/wiki/Maxima_\(software\))

------
miki123211
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...](https://github.com/sourcegraph/sourcegraph/blob/2.13.0/doc/dev/architecture.md)
[1]
[https://github.com/sourcegraph/sourcegraph/blob/master/doc/d...](https://github.com/sourcegraph/sourcegraph/blob/master/doc/dev/img/architecture.mermaid)

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

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

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

------
guessmyname
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/](https://monodraw.helftone.com/)

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

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

~~~
brbrodude
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](https://github.com/salgadobreno/dme/blob/master/README.md)

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

------
KenanSulayman
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](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](https://i.imgur.com/YOaysWn.png))

~~~
lifthrasiir
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](https://www.unicode.org/reports/tr11/#Ambiguous)

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

------
rb808
btw [http://asciiflow.com/](http://asciiflow.com/) is great for doing ascii
diagrams like these.

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

[https://github.com/linpengcheng/PurefunctionPipelineDataflow...](https://github.com/linpengcheng/PurefunctionPipelineDataflow/blob/master/doc/markdown_literary_programming.md)

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.

------
brbrodude
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](https://github.com/salgadobreno/dme/blob/master/README.md)

------
pdsouza
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/](https://preetam.io/post/s3-static-hosting-https/)

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

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

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

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

~~~
zokier
Found this which looks pretty neat
[https://github.com/jbn/IPlantUML](https://github.com/jbn/IPlantUML)

------
weinzierl
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](https://www.w3.org/TR/WCAG20-TECHS/F72.html)

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

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

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

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

~~~
brbrodude
And DrawIt for Vim

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

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

------
smlacy
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](https://pastebin.com/raw/Bg5L9ZJV)

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

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

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

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

[http://www.dbfree.org/webdocs/1-documentation/0018-developer...](http://www.dbfree.org/webdocs/1-documentation/0018-developers_stuff_\(advanced\)/os_related_stuff/xbase_file_format.htm)

blast from the past!

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

------
wernsey
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](http://www.asciidraw.com/#Draw) [2]
[http://shaky.github.bushong.net/](http://shaky.github.bushong.net/)

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

------
raymondh
These examples were nicely curated. Thank you.

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

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

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

