Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

ASCII art for semantic code commenting

asciiflow.com

Post reply on HN
Print view View original

61–70 of 82 posts

Re: ASCII art for semantic code commenting

#61

Post by sixstringtheory »

w4rh4wk5 wrote: post #30

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. ─ │ ┌ ┬ ┐ ┄ ┆ ├ ┼ ┤ ╲ ╱ ┈ ┊ └ ┴ ┘ ━ ┃ ┏ ┳ ┓ ┏ ┯ ┓ ┏ ┳ ┓ ┏ ┯ ┓ ┅ ┇ ┣ ╋ ┫ ┣ ┿ ┫ ┠ ╂ ┨ ┠ ┼ ┨ ┉ ┋ ┗ ┻ ┛ ┗ ┷ ┛ ┗ ┻ ┛ ┗ ┷ ┛

For those on macOS/iOS, using custom text expansions [0] also helps to do this without having to leave the doc you’re editing. I’ve built up tons of these over the years for things like ⌘ (“commandkey”) → (“rightarrow”) (╯°□°)╯︵ ┻━┻ (“tableflip”) and of course, a party parrot wave for Slack (“parrotwave” → :parrotwave1::parrotwave2::parrotwave3::parrotwave4::parrotwave5::parrotwave6::parrotwave7:). They can sync over iCloud and you can export/import them with plists.

I now want to add table characters like these, just need to come up with a good naming convention…

[0]: https://support.apple.com/en-gb/guide/mac-help/mh35735/12.0/...

Re: ASCII art for semantic code commenting

#62

Post by sixstringtheory »

KMnO4 wrote: post #48
sprucevoid wrote: post #41

Earlier quoted context omitted.

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.

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

And in the jump bar (^6, which is then filterable by typing) long before Xcode had the minimap!

Re: ASCII art for semantic code commenting

#64

Post by kazinator »

In the save dialog,"Extended Ascii" should probably be called "Unicode" or "Utf-8" or something. Obviously, no standard named "ASCII" provides box drawing characters and arrows.

The Freeform tool is missing support for the brush consisting of spaces, which would make it useful as an eraser.

Re: ASCII art for semantic code commenting

#65

Post by sixstringtheory »

user-the-name wrote: post #57

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.

IMO text still provides the best combination of flexibility, power, simplicity and accessibility.

A screen reader can’t describe a JPEG or animated GIF. You can’t diff images/animations as easily as text. You can’t automatically translate text in images. Images and their toolchains like imagemagick introduce attack vectors. They take up more disk space. You can’t change the font of text in images. Text in images is not greppable.

Do you need to change some text in that documentation image? Hope you have the vector-based original!

And FWIW, Xcode’s rendering of markdown files and markdown doc comments with media assets in playgrounds isn’t the best experience, IMO.

Re: ASCII art for semantic code commenting

#66

Post by unwiredben »

KMnO4 wrote: post #48
sprucevoid wrote: post #41

Earlier quoted context omitted.

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.

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

I think that might be derived from The "#pragma mark" feature that was in the CodeWarrior IDE which could be used to have annotations show in the drop-down list of functions in the code editor

Re: ASCII art for semantic code commenting

#67

Post by jimmygrapes »

w4rh4wk5 wrote: post #35
wycy wrote: post #34

Earlier quoted context omitted.

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.

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: ┌───────────┬────────────────…

Biggest problem is with mobile / low horizontal resolution displays. I don't mind scrolling left and right, but in some cases the wrapping is forced (as on the HN phone app I'm using, Materialistic) and it becomes a mess. I've longed for some kind of markup system that allows for textual data to be formatted in tabular fashion irrespective of the character size of the contents, like ummmmmm HTML

Re: ASCII art for semantic code commenting

#68

Post by alisonkisk »

misnome wrote: post #32
w4rh4wk5 wrote: post #30

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. ─ │ ┌ ┬ ┐ ┄ ┆ ├ ┼ ┤ ╲ ╱ ┈ ┊ └ ┴ ┘ ━ ┃ ┏ ┳ ┓ ┏ ┯ ┓ ┏ ┳ ┓ ┏ ┯ ┓ ┅ ┇ ┣ ╋ ┫ ┣ ┿ ┫ ┠ ╂ ┨ ┠ ┼ ┨ ┉ ┋ ┗ ┻ ┛ ┗ ┷ ┛ ┗ ┻ ┛ ┗ ┷ ┛

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.

No post body was provided.

Re: ASCII art for semantic code commenting

#69

Post by SAI_Peregrinus »

lelandbatey wrote: post #37
wycy wrote: post #34

Earlier quoted context omitted.

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.

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 distractin…

It's also extremely useful for bit-mapped registers in embedded code.

EG the TI bq25155[1] battery charge controller PCHRGCTRL register (page 52) is divided into 3 fields. It can be quite helpful to show the layout before code to set the range.

   /*
    * ┌───────────────┬──────────┬─────────┐
    * │ ICHARGE_RANGE │ RESERVED │ IPRECHG │
    * │      7        │   6-5    |   4-0   |
    * └───────────────┴──────────┴─────────┘
    * This function sets the precharge current
    *  and fast-charge current step size the
    *  nearest 1.25mA (
etc, etc.

[1] https://www.ti.com/lit/ds/symlink/bq25155.pdf

Re: ASCII art for semantic code commenting

#70

Post by emmanueloga_ »

In general I feel like formats like ascii and even markdown are not great for editing. Most useful data has some sort of structure that is mostly lost when using plaintext or even MD.

A simple example is markdown tables... sorting, inserting and removing columns, etc. is incredibly tedious and probably requires tools to draw, anyway.

In this line of thought, a tool like Graph::Easy sounds like a better way to come up with ascii boxes and arrows [1] (this particular tool can output other formats too).

As a plus, the underlying data can be reused for something other than docs (generating code, scaffolding directories and files, etc).

1: http://bloodgate.com/perl/graph/manual/overview.html

Post reply on HN