9 ms·
Explaining Code Using ASCII Art
- TuringTest 4y agoI wish more code would work like the 2dmatch example of "very cool special case where the ASCII art is also code". Use the representation that shows the relevant information in the most direct form, rather than translating it from an abstract description as sequential code instructions. The GPL license describes source code as "the preferred form of the work for making modifications to it". Sometimes the preferred form that conveys the most information is a 2D visual representation, and it would be sleek if we had more parsers capable of extracting case specifications directly from that format.
- ywain 4y agoI get that it's because the author collected these examples from Twitter, but I find it upsetting that all this ASCII art is presented as pictures instead of... ASCII.
- kzrdude 4y agoHe beats expectations by linking to the actual source code
- chrismorgan 4y agoBut… but… when you have identified where it comes from, why would you go to the trouble of putting the images in rather than copying the code? I would genuinely expect copying the code to be easier, and it’s clearly better and more consistent.
- rocqua 4y agoThis gives a consistent and faithful image. Doing it as plaintext would cause problems with reflowing, weird scrolling boxes, and generally might have you fighting with the browser text renderer.
- chrismorgan 4y agoConsistent? Faithful? I see a whole bunch of images in different styles with different fonts, colours, fairly consistently the wrong line-heights, and even severe JPEG artefacts in at least one case. Doing it in plain text with `white-space: pre` (the default for the <pre> element) would work better.
- rocqua 4y agoConsistent over devices, not Consistent between the images. The point is that jpeg rendering is a whole lot more consistent between devices than html rendering.
- Akronymus 4y agoBecause making the code render properly would require a JS library. (Only slightly sarcastic, as I genuinly have heard similar arguments before)
- SeanLuke 4y agoWait, wait, wait. This entire webpage has examples of ASCII art, and yet 100% of the examples are bitmaps?
- tnzk 4y agoIsn't it fair considering how easy they could be broken due to the difference between environments?
- Cthulhu_ 4y agoPut them in `<pre>` tags and they should render as monospace and the whitespace as-is at least.
- deleted 4y ago[deleted]
- jylam 4y agoThey are JPEGs, even. How sacrilegious.
- gpmcadam 4y agoto be fair, mobile users are probably grateful of that
- xdrosenheim 4y agoNot me, as they are all in different resolutions, having to zoom out, to zoom in, and zoom in again. Simple text would be better.
- diarrhea 4y agoThe author collected these from a Twitter thread of theirs, in which the artworks had to be shared as images. Converting all back to text would be laborious.
- chrismorgan 4y ago
- jraph 4y agoI personally like ascii art drawings to explain things in the code, but it likely makes the life of blind programmers harder when they try to browse the code. I guess it should be used with parsimony and completed with a textual explanation. I don't know if there are tools to easily skip blocks of ascii art.
- zelphirkalt 4y agoI like doing things in plain text and I like ASCII art. However, this is tedious work, if you don't have the tooling to maintain these "diagrams", when things change. The table of "The layout of a data structure in the Jikes RVM" for example. Imagine, if suddenly there was a new attribute in one of the tables, which has a longer name than any of the previously existing ones. Great fun to manually widen the whole thing. With multiple cursors easily possible, but even then it sucks and there are other scenarios, where it gets much worse. In Org mode I could imagine managing such a table and then copying it back into the code comment. And maybe Emacs' ASCII art drawing mode (forgot its name) would help me with other shapes, but drawing something like an ERM or so is still tedious. Maybe those ASCII art diagrams could be created, when the design is already finished.
- TuringTest 4y ago> I like doing things in plain text and I like ASCII art. However, this is tedious work, if you don't have the tooling to maintain these "diagrams", when things change. Not having integrated built-in tools to properly maintain this type of representation is a missed opportunity. IDEs went the copy/paste and word replace route, and the few diagram and table drawing tools in ASCII are often in separate applications, reducing their usefulness.
- comment500 4y agoMaybe the universal solution to this is for the Unicode Consortium to dedicate a set of codepoints for encoding SVG or something similar. Then the system text renderer can be responsible for drawing these diagrams, and they can be embedded anywhere in text. It would also have the side benefit of letting people draw their own emojis, rather than waiting some time from months to never to have their suggestions included in the next Unicode release.
- rocqua 4y agoI beg you, do not give them ideas. Leave plaintext to be as plain as possible. Emoji were already a bad compromise made to get Japanese encodings to sort-of work. Leave markup to general markup languages. Don't make unicode even more convoluted.
- rkangel 4y agoI love asciiflow.com for creating these sort of pictures. I'm a firm believer that the closer your documentation is to your code the better maintained it will be.
- rocqua 4y agoCould this kind of documentation be an exception? After all, it can be quite hard to edit these pictures.
- rkangel 4y agoI think you want to lean heavily into the words and use pictures sparingly where they really add value. They're also not completely uneditable - you can just dump them back in asciiflow and fiddle with them if you want to make a change. I also find that usually the pictures capture a fairly high level structural concept - the sort of thing that changes a bit less. Sometimes I do a message sequence chart and editing to add an extra message is usually pretty easy.
- wernsey 4y agoI really liked the simplicity of the older asciiflow. So much so that I keep a bookmark to the wayback machine for it [1] Not too long ago I had a project that was implemented as a complex state machine where the requirements kept changing, and keeping the documentation as an ASCII diagram in the source code had a couple of benefits: * It meant that the documentation could be updated when the code had to be changed * I didn't have to hunt for the diagrams on the project wiki when I made these changes. * The diagram was kept in version control with the rest of the code. Each commit/branch had a diagram that accurately reflected its state. I could then use Ditaa to convert the diagram to a more appropriate format when updating the project's wiki or emailing the customer [1] https://web.archive.org/web/20130813045206/http://www.asciiflow.com/#Draw https://web.archive.org/web/20130813045206/http://www.asciif... [2] https://github.com/stathissideris/ditaa https://github.com/stathissideris/ditaa
- deleted 4y ago[deleted]
- sharmin123 4y ago[dead]
- JonathanBeuys 4y agoWhy not UTF-8 art? I guess we could make much nicer diagrams with then?
- rocqua 4y agoI imagine it gets very font-dependent what the results actually look like, sticking to ASCII gives great reproducibility guarantees.
- 867-5309 4y agothat's anachronistic since ASCII predates UTF8 creators of 8bit games didn't have the technology to create 64bit games, yet today we create 8bit games for 64bit machines
- timvisee 4y agoI put some basic ASCII art explaining concepts in my article here[1], some might like to check it out: [1]: https://timvisee.com/blog/solving-aoc-2020-in-under-a-second/ https://timvisee.com/blog/solving-aoc-2020-in-under-a-second...
- Linda703 4y ago[dead]
- jka 4y agoShameless appeal for code commentary review: This reminds me of a code comment I wrote about some web crawling code that is intended to maintain a continuous web address "flow graph", matching any origin URL(s) (the 'water table' of a web page) down to the current location of that page on the web (the 'river delta'). This can be complicated because old URLs may be redirected (HTTP 301, 302) to different locations over time, often for SEO reasons or due to change of domain ownership. Does the code comment linked below make sense? I'd really appreciate any feedback and improvements: https://github.com/openculinary/backend/blob/5116c4f5d39dae1f992836c28041722b9893d7de/reciperadar/workers/recipes.py#L60-L116 https://github.com/openculinary/backend/blob/5116c4f5d39dae1... (and yes, I realize the ASCII art here pales in comparison to some of the visually appealing and clear diagrams shared in the article. I'm doing my best :))
- deaddabe 4y agoI wonder how this kind of schematics would sound like when using a screen reader. Hopefully the schematics can be passed if the screen reader struggles to read it, or read an "alt" alternative text instead. But I doubt it. After seeing how a person uses a screen reader, I think using a spreadsheet is sometimes more accessible than ASCII art because I guess screen readers cannot interpret ASCII characters in terms of columns and lines. If I would have to document a table into the code, I would try to use as little ASCII characters as needed, in order to not confuse the screen reader.
- lizardactivist 4y agoThese days I tend to think that code should contain guides and markers so developers can find their way, but actual documentation is best placed in separate files outside of the code.
- explodingwaffle 4y agoThis one has to be my favourite- I thought maybe whoever transcribed the source code listing for the AGC to GitHub took some artistic license- but no, it's there in the original scans! https://archive.org/details/Comanche55J2k60/page/n1027/mode/2up https://archive.org/details/Comanche55J2k60/page/n1027/mode/...
- captn3m0 4y agoFor generating protocol headers: https://www.luismg.com/protocol/ https://www.luismg.com/protocol/
- okamiueru 4y agoThis isn't a very good solution, IMHO. Or, it doesn't scale. If you find yourself with an existing solution that doesn't scale for what you need it to, cut your losses and find a better tool or solution. Some simple visualization using ASCII is fine. Something you can create from scratch and otherwise modify in as much time as it would take to document code. But, if you need a sequence diagram, or flow chart, what not. The tradeoff for maintenance and lack of readability makes it look silly. The "why was this developer wasting time doing things with the wrong tools"-kind of silly. If you need complex diagrams. Create them using draw.io or plantuml, and add them to the source control. Generate images which you instead reference in the documentation in code. Tools such as Doxygen and other such tools would be able to pull in the images and actually look good. This is both maintainable, and scalable.
- machinerychorus 4y agoI'm not sure I agree with "it doesn't scale". It scales just as well as writing code by hand does! PlantUML/mermaidjs do hit a sweet spot IMO, of having the chart defined as plaintext but rendering a pretty picture. The only way these could be improved IMO is if the ascii "code" for the diagram was also an actual diagram you could understand without running it through the parser.
- okamiueru 4y agoI should clarify what I mean with scaling. I was trying to describe complexity of maintaining the illustration for the complexity of what it is illustrating. For ASCII art, this is far from linear, in most of the examples shown. Consider some of the more complex ones shown in the linked article. The minor added complexity of adding a field, suddenly might mean you need to remake parts, or even entire visual art for it to stay congruent. You'll have software engineers hitting spacebar a few hundred times just to align things right. With proper tools, you'd just add the field, and that's it.
- unholiness 4y agoAny visual information that needs to be understood by a human doesn't scale. ASCII UMLs might scale slightly less well than, say, powerpoint UMLs, but having them right there in the code comment in cases that do fit is splendid.
- JKCalhoun 4y agoA lot of hate in this thread. If you stop analyzing the utility/practicality/extensibility of it you might admire just how beautiful it is (or try to picture the tired dev taking a coding break to do some "art"). Love this stuff.
- whoibrar 4y agoFor me to draw even a simple ascii art it takes more time, attention, effort than any graphical. I can't crop, can't mirror, can't rotate, can't zoom, can't add secondary or any color for that matter. I know the process is slow, and obviously not efficient by any measure. yet I do it and ... I love ASCII ART. Its elegance is in its simplicity. To be able a draw anything from simple boxes[0] to Mona Lisa[1] to Porn[2] using nothing but bunch of plain ascii characters just blows my mind. To craft is to hand place each character, at its right place without disturbing anything around, which feels nothing less than crafting a glass-piece. Links : [0] : https://www.asciiart.eu/art-and-design/borders https://www.asciiart.eu/art-and-design/borders [1] : https://www.asciiart.eu/art-and-design/mona-lisa https://www.asciiart.eu/art-and-design/mona-lisa [2] : https://www.asciiart.eu/people/sexual/women https://www.asciiart.eu/people/sexual/women
- layer8 4y ago[2] That’s erotica, not porn.
- pyautogui 4y agoHardly: erotica is, at least by my definition, textual porn that semantically arouses. This is very clearly visual porn, though it may be textual.
- dragonwriter 4y ago> erotica is, at least by my definition, textual porn That's not what the word means in normal use.
- 4y ago
- Hernanpm 4y agothanks, this is what I was looking for for my upcoming interviews.
- matrix8967 4y agoMan - this is my fkn brand. Plain text is almost a universal truth -- and it's easy to church up your documentation with a well presented ASCII chart. Some ANSI Color Codes and ASCIInema can carry you a long way. Here's a list of plain text information tools from my notes: https://mbarkhau.keybase.pub/asciigrid/ https://gitlab.com/mbarkhau/asciigrid/ ascii-tables is exactly what is says on the label. https://ozh.github.io/ascii-tables/ https://github.com/ozh/ascii-tables/ https://www.netpen.io/main/ https://github.com/ebirger/netpen/ svgbob and svg-term are both great for creating SVGs out of these plain text files: https://github.com/marionebl/svg-term-cli/ https://ivanceras.github.io/svgbob-editor/ https://github.com/ivanceras/svgbob/ Here are some TUI/CLI focused frameworks. These are over kill for me - but maybe useful to someone here: https://www.textualize.io/ https://charm.sh/ http://maaslalani.com/slides/ https://github.com/peterbrittain/asciimatics/ TUI/Text-Based presentaion tools: https://sli.dev/ https://github.com/slidevjs/slidev/ https://github.com/maaslalani/slides/ http://maaslalani.com/slides/ https://github.com/d0c-s4vage/lookatme/ https://github.com/chunqiuyiyu/ervy/ Honorable Mention goes to wtf-util and it's TUI configurator: https://wtfutil.com/ https://github.com/ggerganov/wtf-tui Thanks for coming to my ted talk!
- mbar84 4y agoThanks for the shoutout. AsciiGrid is dockerized should you want to run it yourself, for example because the keybase website happens to not be serving it anymore: https://github.com/mbarkhau/asciigrid#docker https://github.com/mbarkhau/asciigrid#docker
- throwamon 4y ago> Plain text is almost a universal truth Would you mind explaining what you mean by this? I take it you mean it ubiquitous, which of course it is, but as a phenomenon I'd much rather see things that look like they come from the real world, with color, depth, texture, and I'd much rather see a future where interactions with computers are moving in that direction.
- grandchild 4y agomaybe add https://asciiflow.com https://asciiflow.com ?
- ssd8991 4y ago[flagged]
- lufte 4y agoGood stuff. I wonder if there's a way to "detect" ASCII art automatically by crawling open source repositories.
- _8j50 4y agoReminds me of Radare2's ascii function/code graph.
- swyx 4y agoi have a hobbby of collecting diagramming tools: - https://fatiherikli.github.io/archetype/ https://fatiherikli.github.io/archetype/ - https://textik.com/#a4ec12a68785f25f https://textik.com/#a4ec12a68785f25f - http://asciiflow.com/ http://asciiflow.com/ - https://monodraw.helftone.com/ https://monodraw.helftone.com/ - text to diagramming tools [list](https://smusamashah.github.io/text-to-diagram https://smusamashah.github.io/text-to-diagram) more: https://github.com/sw-yx/spark-joy/blob/master/README.md#ascii-art https://github.com/sw-yx/spark-joy/blob/master/README.md#asc...
- matrix8967 4y agoOh man - I'm def gonna spend some time picking the bones of this list -- great finds. I have a whole section of my notes dedicated to ASCII Art in the purely creative/crack/BBS scene. Unicode/Cyrillic fonts used by loud girls on instagram: https://coolfonts.text-generator.org/ https://www.messletters.com/en/ https://github.com/sepandhaghighi/art Some creative ASCII tools: https://github.com/maaslalani/draw https://blocktronics.github.io/moebius/ http://picoe.ca/products/pablodraw/ https://ivanceras.github.io/svgbob-editor/ http://www.torchsoft.com/en/aas_information.html https://github.com/hpjansson/chafa/ Here's some ANSI and BBS scene stuff: https://www.asciiarena.se/ https://16colo.rs/ https://www.ansilove.org/ https://www.trueschool.se/ https://www.teletextart.com/ https://www.pouet.net/ https://github.com/NuSkooler/enigma-bbs Like most of us - I grew up with mostly Async communication online. I'm still out here dishing out emoticons like it's 1998 and every kilobyte counts. (•_•) ( •_•)>⌐■-■ (⌐■_■)
- swyx 4y ago"Unicode/Cyrillic fonts used by loud girls on instagram" had me LOLing hahahaha we can be friends
- therealmocker 4y agoI wonder if Github Co-pilot or DALL-E type work could be expanded to generate ASCII diagrams (or art) based on descriptions provided.