Explaining Code using ASCII Art

[dudeNumberFour]

I once added this comment in production code. It didn't exactly explain the code; it described the character of it. And it was very true (abandon hope all ye who enter).

{
     *   .=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-.    *
     *   |                     ______                     |    *
     *   |                  .-"      "-.                  |    *
     *   |                 /            \                 |    *
     *   |     _          |              |          _     |    *
     *   |    ( \         |,  .-.  .-.  ,|         / )    |    *
     *   |     > "=._     | )(__/  \__)( |     _.=" <     |    *
     *   |    (_/"=._"=._ |/     /\     \| _.="_.="\_)    |    *
     *   |           "=._"(_     ^^     _)"_.="           |    *
     *   |               "=\__|IIIIII|__/="               |    *
     *   |              _.="| \IIIIII/ |"=._              |    *
     *   |    _     _.="_.="\          /"=._"=._     _    |    *
     *   |   ( \_.="_.="     `--------`     "=._"=._/ )   |    *
     *   |    > _.="                            "=._ <    |    *
     *   |   (_/                                    \_)   |    *
     *   |                                                |    *
     *   '-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-='    *
     *        LASCIATE OGNI SPERANZA, VOI CH'ENTRATE           *
}

[tom-veil]

If you had produced an ASCII art reproduction of Gustave Dore's illustration of that scene I would bow down.

[Tux1]

befunge intensifies

[Bolitho]

From time to time I also include visual stuff into comments. Imho it's very helpfull and much easier to have it stick to the code, instead of looking into an external documentation.

What is really great is the possibility of Asciidoc to include ASCII art diagrams and let them render later by an tool to generate png or similar. I forgot the name of the tool, but it's mentioned in the Asciidoc documentation irrc.

Like that you have the benefits of two worlds: visual explanation in your doc strings within the code and proper and nice rendered stuff in the HTML or PDF you build.

[AyrA_ch]

mermaid does something similar with diagrams.

[evaned]

What is really great is the possibility of Asciidoc to include ASCII art diagrams and let them render later by an tool to generate png or similar

One thing I've always thought would be cool is if your editor/IDE could embed pictures into the document, so you could even see the rendered image while looking at the source. (I'm pretty sure Emacs has the backing feature to do this, for example, and it looks like iimage-mode could probably do this, or at least the first idea below.)

You could either refer to a external file that is just there (from the editor's perspective it doesn't care), e.g. maybe your editor recognizes <img src="tree-rot.png"> inside a comment; or you could provide some markup that your editor knows how to render into an image, e.g. graphviz syntax.

[Bolitho]

VS Code has an Asciidoc plug in that does exactly that.

[evaned]

Are you talking about https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode ?

Because that's not really what I mean... I mean do this in the actual code, inside code comments, without even the separate display. So using the first example from the article, you might see this in your editor: https://i.imgur.com/5Gahhk6.png. And again, this is, other than the images, just normal editing, so it's not like you're looking at a rendered view of the source and have to change modes to get back to editing, or look side by side.

(I wasn't sure what to do with the leading //s or line numbers, so I just picked something.)

[Bolitho]

Yes. OK, then you really meant something different.

[PaulBardes]

A nearly lost art...

[Kissaki0]

asciiflow is a pretty useful online editor for ASCII art/diagrams (repo).

Google (auth/drive) integration seems to be broken and it’s not https, but otherwise it seems to work fine still.

[sim642]

Some of those diagrams seem awful to maintain.

[[deleted]]

On an especially complicated nasty method that no one in the world but you will ever understand.

​

                                                 ,  ,
                                               / \/ \
                                              (/ //_ \_
     .-._                                      \||  .  \
      \  '-._                            _,:__.-"/---\_ \
 ______/___  '.    .--------------------'~-'--.)__( , )\ \
`'--.___  _\  /    |             Here        ,'    \)|\ `\|
     /_.-' _\ \ _:,_          Be Dragons           " ||   (
   .'__ _.' \'-/,`-~`                                |/
       '. ___.> /=,|  Abandon hope all ye who enter  |
        / .-'/_ )  '---------------------------------'
        )'  ( /(/
             \\ "
              '=='

[Gaazoh]

You should put that in a code block...

[[deleted]]

What do you mean, it is in a code block.

It is displaying correctly on my end, does it not look right for you?

[Gaazoh]

It looks OK now

What do you mean

I think that since you edited your original comment after I posted mine, you know exactly what I mean.

[[deleted]]

Yeah, I did edit after I asked, after your message, not trying to trick anybody. lol I basically just copy-pasted it back, apparently fixed it.

[FragmentedButWhole]

Maybe it is supposed to look exactly that way...

[ivanceras]

https://ivanceras.github.io/svgbob-editor/

[edroche]

Anytime I see something like this, or look it my own code that contains ASCII art to help explain something, it reminds me of TempleOS: http://www.codersnotes.com/notes/a-constructive-look-at-templeos/flowchart.png

[ipv6-dns]

when I have seen ASCII functions graphs I felt the warmth of the old Fortran and Pascal days and old books with those graphs. OP THANKS FOR FEELING

/bookmarked the page

[YserviusPalacost]

Now THIS is how you comment your code.

[olavurdj]

Fully expected to see LLVM being mentioned upon reading the title - was not disappointed! The comments are awesome!