[HN Gopher] ASCII art for semantic code commenting
___________________________________________________________________
ASCII art for semantic code commenting
Author : anonymous_they
Score : 216 points
Date : 2022-02-09 14:55 UTC (8 hours ago)
(HTM) web link (asciiflow.com)
(TXT) w3m dump (asciiflow.com)
| stabbles wrote:
| I recently discovered https://excalidraw.com/ for informal
| diagrams that work well in presentations
| samwillis wrote:
| Another good one is https://www.tldraw.com
|
| Being built by @steveruizok very much worth a follow on
| Twitter:
|
| https://mobile.twitter.com/steveruizok
| ynac wrote:
| While being an almost daily user of MonoDraw, I utilize Valery
| Kocubinsky's Table Editor package for Sublime at least a dozen or
| more times every day. All my daily habit, scheduling, trackers,
| and labor is in some sort of table. Thank you, Valery!
|
| It isn't maintained but 90% of the features work fine. The
| project was picked up and is current on Atom.
|
| Grabbing boxes for commenting is within scope of Table Editor but
| again, Monodraw offers some great flexibility. If you're working
| with code that's getting printed in a newsletter, drop it in a
| Monodraw box (remove border) and you can add call-outs on either
| or both sides of the code and paste it all in the newsletter.
| Looks nifty, and keeps the aesthetic consistent.
| Sublime Table Editor ...
| https://packagecontrol.io/packages/Table%20Editor Atom
| Table Editor ...... https://atom.io/packages/table-editor
| Vim .................... https://github.com/dhruvasagar/vim-
| table-mode
| celie56 wrote:
| If you use nvim, there is a similar tool called venn.nvim:
| https://github.com/jbyuki/venn.nvim
| jeppesen-io wrote:
| Ohhh! Lovely. I was hoping someone might post a nice nvim
| plugin! Think I'll open a PR to add this to Nix[OS] this
| weekend
| verdverm wrote:
| I love this plugin, came here hoping to see it so I wouldn't
| have to go lookup the link.
| kitd wrote:
| A few years back I wrote a tool that would convert Ascii flow
| diagrams in source code comments to equivalent source code
| declarations that implemented the flow. The idea being that the
| comments didn't just describe the flow visually, but actually
| defined it.
|
| Tools like this helped greatly with that. Plain old text files
| don't lend themselves well to such 2D visual descriptions.
| user-the-name wrote:
| It's amazing that it is 2022, and not only _can_ we not put any
| kind of media in source code comments, nobody even entertains the
| idea that it could be possible.
|
| Programming tooling really is living in the dark ages sometimes.
| marcellus23 wrote:
| Monodraw is great for this too on Mac:
| https://monodraw.helftone.com/
| IBCNU wrote:
| Monodraw is awesome, and has a really great desktop interface.
| jstanley wrote:
| Cool idea. I recently wanted to draw a diagram of triangles in a
| code comment, but unfortunately this tool doesn't seem to let you
| draw lines which aren't axis-aligned, so it doesn't help for
| that.
| kdmoyers wrote:
| I've discovered that the crippling bug in asciiflow [1] is not
| present when running it in FireFox, to my great relief.
|
| [1] https://github.com/lewish/asciiflow/issues/185
| zokier wrote:
| What makes this "semantic code commenting"
| adrianomartins wrote:
| Wow. This is one of those "I bet someone has already done that"
| tools that developers wish they had but not as much to go and
| search for it. Bookmarked and shared. Thanks ;)
| VikingCoder wrote:
| Why don't we all use code editors that know how to render things
| like Graphviz and Markdown with lists, tables? Maybe in a side
| window rather than in the main display, but like, come-on...
|
| Like, Visual Studio Code supports something like this:
|
| https://marketplace.visualstudio.com/items?itemName=joaompin...
| roosgit wrote:
| For longer CSS files I use ASCII text to mark and visually
| separate the breakpoints. An advantage of this is the ability to
| see the breakpoints in the minimap. Something like this:
| https://css-tricks.com/wp-content/uploads/2015/09/mini-map.j...
|
| There's even a Sublime Text plugin to generate this text.
| sprucevoid wrote:
| Nice. Though it makes me think it would be nice to have this as
| a built in code editor minimap feature without the multi line
| ASCII code. The editor would parse special tags in comments and
| overlay the minimap with the tag text in big letters.
| KMnO4 wrote:
| This is one of my favourite features of XCode. If you "//
| MARK:" lines, they'll show up in the minimap.
|
| Eg. https://miro.medium.com/max/1400/1*j38oOm3Pt5AMnDI3HQ6TGQ
| .pn...
|
| Screenshot stolen from this Medium[0].
|
| [0]: https://medium.com/@mumtaz.hussain/xcode-11-now-makes-
| mark-c...
| sprucevoid wrote:
| Excellent. I hoped for a similar VS Code extension but
| found none. There's only Banner comments[0] to ease
| converting a string to large ASCII letters inline. [0]: htt
| ps://marketplace.visualstudio.com/items?itemName=heyimfuz..
| .
| roosgit wrote:
| Yeah, a bit like how CSSEdit used `@group`
| https://live.staticflickr.com/112/291326042_18115aa3c1_b.jpg
| seumars wrote:
| At that point it would be better to just split it into several
| files though.
| oneeyedpigeon wrote:
| Maybe it is, maybe this is just an intermediate file in a
| build process, optimised for readability.
| ericmcer wrote:
| I was daydreaming about something like this the other night. This
| is even cooler than what I was picturing! My only complaint is
| the download arrow threw me off for a bit, I wanted to copy to
| clipboard but did not realize that was hidden behind the arrow.
| Switching that icon to a clipboard that pops the modal might add
| some clarity.
| a2800276 wrote:
| It's so nice to see all this interest in ASCII art.
|
| \o/ -huzzah
|
| I still use Jave (http://www.jave.de/#description) occasionally,
| but it's beginning to show its age. It does have some nice
| features, though that asciiflow is missing: figlet font support
| and ( _gasp_ ) circles!
|
| Some other tools worth mentioning here among aficionados are PIC
| ( https://en.wikipedia.org/wiki/PIC_(markup_language) ) and of
| course cowsay. Someone already mentioned plantuml.
| dbjorge wrote:
| This is a neat tool, but unfortunately, text art like this
| generates is extremely unfriendly to folks that use screen
| readers. If you do use this for comment documentation, consider
| making sure that there is also a written description above/below
| it with equivalent descriptive content.
| notRobot wrote:
| This is a very good point that I hadn't considered for some
| reason. Thanks!
| ChrisArchitect wrote:
| Some recent discussion from 8 months ago:
|
| https://news.ycombinator.com/item?id=27536253
| bloak wrote:
| EDIT: Deleted before I get even more downvotes.
| anordal wrote:
| On a general note, I think it's time to call things "text"
| instead of "ascii".
|
| Every time someone utters the word "ascii", they just mean
| text. Saying "I'm using ASCII" doesn't mean anything anymore,
| because nobody uses EBCDIC anymore - you are, no matter what,
| effectively using a superset of ASCII, by default UTF-8. The
| real question is which one.
| wlkr wrote:
| It seems to work exporting to both ASCII standard and extended
| for me.
| bloak wrote:
| Ah, yes, I can see it now, but that option is almost
| invisible for me. I have to operate some scroll buttons at
| the edge to see the words "ASCII Extended".
| ivanceras wrote:
| I made something[0] similar, with a few more bugs that are yet to
| be solved [0]: https://ivanceras.github.io/svgbob-webview/
| jaster wrote:
| For emacs users, there are some modes with similar
| functionalities (as expected from emacs!): picture-mode and
| artist-mode
|
| See for example
| http://xahlee.info/emacs/emacs/emacs_ascii_diagram.html
| jordigh wrote:
| Came here to say this. If it's text, Emacs can handle it.
|
| Oh, also, if you want your ASCII diagrams to render into pretty
| pictures, I found org-mode + ditaa to work quite nicely:
|
| https://www.orgmode.org/worg/org-contrib/babel/languages/ob-...
| everybodyknows wrote:
| Another option for rendering (to SVG) is _goat_ :
|
| https://github.com/blampe/goat
| andix wrote:
| PlantUML can export to text too. And it aligns all the boxes and
| arrows for you.
|
| Still, great idea and great implementation :)
| samatman wrote:
| I'm going to second this one, and add that diagrams are a real
| weak point for accessibility in general, one which using
| textual drawings exacerbates.
|
| PlantUML is readable by screen readers and contains the same
| information as the diagram it generates, which is the optimal
| balance between using visual diagrams as part of software
| development while not excluding the vision-impaired completely
| in so doing.
|
| To be clear, I'm not scolding anyone for using ASCII diagrams,
| especially given that code remains stubbornly text-only. Just
| boosting awareness of PlantUML in terms of its accessibility
| advantages. I can mention meaningful diffs in version control
| as another advantage!
| moonchild wrote:
| See also: rexpaint - https://www.gridsagegames.com/rexpaint/
| thanatos519 wrote:
| I use TheDraw in DOSBox. Still the best!
| dspillett wrote:
| I've seen this a few times. The key limit is that once drawn the
| characters are set, you can't move the drawn objects around.
|
| What I'd like is something like drawio for ASCII/Unicode. I've
| been thinking of writing my own for years, but that'll probably
| never happen so I'll just keep mentioning the idea when similar
| apps come up in the hope I inspire someone else!
| taterbase wrote:
| Perhaps I'm misunderstanding you but this tool expressly has a
| select and move tool.
| dspillett wrote:
| It does, but that selects and moves the cells not the objects
| and then redraws the cells? Actually, going back to have a
| play I see that it does allow some modification of existing
| objects but it isn't terribly flexible.
|
| I've just done a quick search and found one that I've not
| spotted before, which is a bit closer to what I want in that
| one respect, but not nearly complete overall (and not seen a
| check-in in 8 years): https://textik.com/ - that might
| illustrate the key difference that I see missing in
| asciiflow.
| lijogdfljk wrote:
| If i understand you, the Mac-only Monodraw handles this
| fine. It lets you draw objects, point to objects (say like
| a diagram), and then move them around with the pointers
| auto adjusting to remain correct.
|
| It's a shame that it's mac only.
| dspillett wrote:
| _> It 's a shame that it's mac only._
|
| Yeah, that looks to fit the bill nicely but is no use to
| me with my current mix of operating systems.
| eenell wrote:
| You can drag edges, but it doesn't seem to have a concept of
| a "square" beyond the tool itself. So after you've placed it,
| you can't move individual shapes around. The select works
| more like a text-editor's highlighter than something like the
| lasso tool in draw.io
| junon wrote:
| Hey, maintainer here (sorta). We've both been super absent the
| last few years unfortunately but this was ultimately on our
| list for V3.
|
| Now I just need to find some spare time...
| anonymous_they wrote:
| It's a little tedius, but you can highlight sections and then
| drag the highlighted section around.
|
| Also it would be nice to have some way of snapping boxes to a
| grid. Similar to creating new elements in figma. It was hard to
| tell when if all the boxes I made were aligned / same size.
| rep_movsd wrote:
| You should add double line drawing characters and shadows
| (remember the DOS version of Norton Utilities?)
|
| Maybe make a theme set - Turbopascal style, QBasic style etc
| w4rh4wk5 wrote:
| For what it's worth, I keep a file in my home folder containing
| some box drawing characters. It's not super fast to draw by copy-
| paste but the result usually looks quite nice.
| - | + + + - | + + + \ / - | + + +
| - | + + + + + + + + + + + + - | + + + + + + + + + + +
| + - | + + + + + + + + + + + +
| themodelplumber wrote:
| Similar here, I use snippets for some of these things as well.
| As long as you're using a monospace font, I find it nice to
| take advantage of things like grid layouts in the extra column
| space for splitting up concepts into groups for example.
| wycy wrote:
| Do you have an example context in which you'd use these? I've
| never thought to do this and am curious about the possibilities
| and use cases.
| keithnz wrote:
| Basically I use the same kind of philosophy as RFCs, and
| document things using ascii art where some kind of diagram
| makes sense. For example, see the TCP RFC
| https://datatracker.ietf.org/doc/html/rfc793 where they use
| it for packet layout, flow diagrams, block diagrams, etc. It
| makes the whole thing self contained, you can copy paste
| diagrams to almost anywhere, easy to modify. Disadvantage is
| in some more complex diagrams it can get noisy
| [deleted]
| w4rh4wk5 wrote:
| Sure, last time I used them I documented some file format I
| needed to reverse engineer.
|
| Here an excerpt. Of course, it's not _necessary_ to do it
| like that. It's just flavor. +-------------
| ---+--------------+----------------+--------------+--
| | Chunk 1 Header | Chunk 1 Body | Chunk 2 Header | Chunk 2
| Body | +----------------+--------------+-------------
| ---+--------------+-- Chunk Header:
| +-----------+-----------------+ | Magic Nr. | Chunk
| Body Size | | 4 Byte | 4 Byte |
| +-----------+-----------------+
| lelandbatey wrote:
| It's fabulous in cases where there's a "big important
| business logic" or a "big important test" with tough to
| eliminate complexity, where you feel a diagram is so
| important that it's worth putting in comments beside said
| code. I do recommend that you be careful with this though; in
| places where it's not common to put ASCII art diagrams in
| code you'll probably receive pushback (it is afterall very
| large and distracting compared to said code). Be ready to
| save an in-code diagram for the 1-to-3 places in the business
| where they'll be a godsend.
| stevewillows wrote:
| Wikipedia has a good page that also includes shading
|
| [1] https://en.wikipedia.org/wiki/Box-drawing_character
| misnome wrote:
| I usually copy from wikipedia but that's that's a good idea. In
| fact, since I have a "cols" command that just prints an ansi-
| colour table, I've just added "box" to do this.
| arjvik wrote:
| can you share the contents of your cols
| script/function/alias?
___________________________________________________________________
(page generated 2022-02-09 23:00 UTC)