[adastra22]

Why would you want to work with the text representation, except when debugging or in the backend? I mean I get why you'd want the text representation to exist--we have mountains of infrastructure around text-based representations of code. Git for version control and LLM code models would work out of the box, for example. But that can all be handled on the backend by transpiling the AST to text as needed. Why would the user need to interact with the textual representation?

Commenting needs to be solved at the language level, and there are many languages that have solved this exact problem. Python, newLISP, and Smalltalk IIRC all have methods for docstring commenting APIs such that the docstring is available as text to the running program / REPL. Use similar syntax to allow any statement to have comments attached, and use this instead of free-form /* */ comments.

[vidarh]

> Why would you want to work with the text representation, except when debugging or in the backend?

How would I communicate about the project to others in e-mails, instant messenger, face to face, in blog posts, in articles, in books?

How would I review diffs of code changes effectively?

That is why.

Find me a representation I can talk about and write about efficiently without screenshots or videos or requiring special software of every recipient on every platform, and you'll have advanced the state of the art in this field immensely.

> that have solved this exact problem

None of the ones you described have solved the problem of mapping between a visual and textual representation of the program seamlessly. Just attaching the comments from a textual version to an AST of the textual version is trivial. That's not the challenge.

> Use similar syntax to allow any statement to have comments attached, and use this instead of free-form /* / comments.

That doesn't get close to solving the issue. When I have a diagram showing the data flow of a piece of code, and I attach a comment to the edge* between the two nodes, in the textual representation where does that comment go? Does it go in the text version of the source node? In the destination node? What if I write a comment in the textual version right before a method call, and then switch to the visual version, does that stay in the source node? Does it become a label of the edge representing the method call? There are tons of edge cases there.

The problem isn't finding a way to attach the comments in the right place, but finding a way that roundtrips perfectly without adding noise in either representation.

[Nzen]

I think that it is probably worth addressing what sort of textual visualization you have in mind. That way, you could disabuse people with naive notions like myself.

I've not used a visual programming language and unit is (currently) hugged to death. But, my experience with graphviz's dot syntax would suggest putting a comment on the (textual) line that represents the edge itself:

  digraph whatever {
    running [ shape = "triangle" label = "program running" ]; # comment on the node itself
    stopped;
    running -> stopped; # comment about the edge
    stopped -> running;
  }

I acknowledge, though, that I'm thinking of this as a dsp-style situation, where a node only connects at its boundaries, rather than in the center (say if a node contains code that would link to another as part of an if expression's body).

(Also, I'm disappointed that I need to resist the urge to talk about Bob Nystom's visual pdf diff, because it seems really cool but is not as credible as the edge directive above. https://journal.stuffwithstuff.com/2021/07/29/640-pages-in-1... , scroll to 3/4 where it says "Here is what all of the proofreading changes look like:")

[vidarh]

> I acknowledge, though, that I'm thinking of this as a dsp-style situation, where a node only connects at its boundaries, rather than in the center (say if a node contains code that would link to another as part of an if expression's body).

I think that might well be one of those restricted situations where visual programming often works well enough that it seems some use. I'm absolutely not saying it can't ever work.

My problem with it is more when you try to do more general-purpose things with it, and you e.g. either end up with a node per method/function call (and maybe then even nodes for argument expressions) or large, complex nodes with internal logic.

I love dot for graphs, but the challenge to me with that approach is that I've not seen a convincing example where you'd then not end up with a mountain of text for even very simple things (and I've sinned badly there myself - one of my own early attempts serialised to XML...) when you decompose the text enough that you can augment it reliably.

E.g. consider a complex expression where that edge is not just a simple state transition, but a method call with arguments, where each argument itself might be a complex expression...

Every attempt I made myself ended up with a textual version that was too verbose to feel viable for communication about the code unless I stripped out so much that the visual tooling effectively became a tool to analyse the textual version, rather than allowing editing on equal footing.