Fredrik 2024-03-18 20:16:09 Is there any wisdom on how to best lay out code in a visual code browser ?
In my experience, code can be layed out either more horizontally on long lines or more vertically on short lines. This is controlled by setting a criterion for how many levels of nesting there can be before a node switches to a multiline layout. Long lines use space efficiently but tend to get hard to read. Short lines are easier to read, as tokens of similar significance line up in columns, but tend to take up much vertical space while leaving most of the horizontal space unused, as the average line is just one key and one value.
Shall I accept that code gets very vertical, and use the free horizontal space to add multilevel navigation panels, or is there a third option that is more horizontal while still easy to read? I can go really fancy and add tables and multiple columns, since I have full control over the layout function, but not all code is regular enough to fit a tabular format, and I cannot require the person editing the code to manually bikeshed it by editing whitespace or dragging around visual nodes. I've seen the horrors of manually bikeshedded plain-text languages and the horrors of node-based languages where the programmer makes a simple one node change and then has to drag all the nodes around so they line up. Are there any examples of interesting solutions to look at?
Here's how I mean a more horizontal layout:
element 1
{
key 1
: value 1,
key 2
: value 2,
key 3
:
surprise
{
key 1
: value 1 } }
element 2
{
key 1
: value 1 }
Here's how I mean a more vertical layout:
element 1
{
> key 1
> : value 1,
key 2
: value 2,
> key 3
> :
> surprise
> {
key 1
: value 1,
},
}
element 2
{
> key 1
> : value 1,
}
In the more horizontal layout, I can barely parse the surprise structure at a glance, and I can barely see if I've made a mistake in editing. It takes a lot less screen space though.
Eli Mellen 2024-03-18 21:00:04 Not sure if this really helps, but, navigating your examples with a screen reader (something I use for work but not full time) the first example is read verbatim, like a sentence, whereas the second example is read in a more structured way, making the user navigate from key to value, etc.
Fredrik 2024-03-18 21:21:38 @Eli Mellen That's the reading you get from the plain text on Slack. In my real app, you get a different reading. I've found it helpful to test my apps with a screen reader, and I've decided to design separately for visual presentation and screen readers, so there's no need to adjust the visual presentation to work with screen readers. Screen readers get the full hierarchy of all nodes, and the user can use the arrow keys to navigate individual nodes. Each node reads a summary, and the user can navigate into it to read more about the child nodes.
Cameron Yick 2024-03-19 04:11:02 I think two general books about typography/ print layout may be relevant to . Both make the point that text is scanned / reread repeatedly. Because it isn’t necessarily read linearly, having “landmarks” that gives your eyes something to hook onto and make related structures chunkable as shapes is valuable. These marks are provided by the indentation. Apart from the words, both of these books practice what they preach when it comes to creative and memorable text layouts.
- what we see when we read by Peter mendelsund
- Seeing with fresh eyes by Edward Tufte
In visual neuroscience they benchmarked the page width at which reading speed / comprehension drops off a cliff aside from the basic physical constraint of reducing the amount of eye or neck movement to follow along.
The specific count varies by language / what comprehension means for your context, but it helps provide empirical backing for the intuition for why there’s a sweet spot in between being vertical vs horizontal heavy.
Your code / json data editor sounds neat. I get your concern about the risk of an author getting caught up in formatting bikesheds. One middle ground that comes to mind looking at your examples is letting the code be autoformatted however, but if I add a comment annotation before a section, in “view mode” for the next section, that section could be forced into a vertical or horizontal mode, whatever I the author recommended.
Fredrik 2024-03-19 07:44:06 Cameron Yick You make an interesting point about having an automatic default but letting the author override it for selected code. This is an idea I have already largely rejected. I don't trust myself to manually format my own code. I have way too much cognitive bias for that, so my formatting choices tell only how I was feeling the day the code was formatted, and what code I was reading earlier that day.
This problem occurs to me with argument lists of function definitions in Rust. Traditionally, argument lists are formatted horizontally, but sometimes they get long, or one argument may have a long name or long type, and then I format them vertically. Then I go edit another function which doesn't have a long argument list, and I format that vertically too, because of the halo effect. Rust has a tool called rustfmt that does exactly this middleground, automatic formatting with manual overriding in places, and I've not found it helpful.
Manual formatting also assumes that everyone views the code the same way as the person who formatted it. That's why we have silly commandments that the tab size must be set to a certain number of columns, or a page must be viewed in IE 5.5 with a screen resolution of 1024×768 pixels, or perhaps worst of all, assuming that everyone will view the code with a monospace font. (I don't, and even the Smalltalk browser from the 1970s didn't.)
Thanks for the book recommendations! I will need to take more time to look at them. I love a good book about typography.
Joe Eagar 2024-03-19 21:53:50 You can do neat things like split horizontal layouts into vertical at the root first and the leaves stay horizontal
Fredrik 2024-03-20 03:29:17 @Joe Eagar The paper assumes that more horizontal is always better, which is what I was questioning. It crams as much as it can into one line, ignoring readability, then breaks when necessary, and then adds more bits and pieces from the parent level horizontally if possible.
Here's an example I made where I depart from traditional plain text code and format a list as a table with a balance of horizontal and vertical spread.
Joe Eagar 2024-03-20 03:43:45 Here's an example of an object literal with vertical and horizontal spacing:
Joe Eagar 2024-03-20 03:45:31 Btw, the underlying system (at least as implemented in Prettier) is flexible enough to achieve basically whatever balance of horizontal and vertical you want, the core insight is just that breaking recursively at a structural level can produce more readable formatting.
Joe Eagar 2024-03-20 03:50:40 If you want to go beyond plain text editors, you could try converting code to/from a HTML representation (or LaTex if such a thing as a real-time renderer for LaTex exists).
Fredrik 2024-03-20 03:50:57 @Joe Eagar I suppose Prettier has some extended variant of the method from the paper. That example of an object literal is interesting. It's the kind of example I was thinking of when asking the question. In ordinary plain text code, I would avoid that, as I don't like the runs of space characters, but in a non-plain text layout I can do such things with advantage.
Joe Eagar 2024-03-20 03:51:43 I actually forked Prettier and added support for aligning columns that way; Prettier by itself doesn't insert quite so much whitespace (I find it easier to read).
Fredrik 2024-03-20 03:56:53 @Joe Eagar There's Typst, which is like Tex but almost real-time. My primary output is a native app where I render directly to a region of pixels, so I have a lot of freedom. Secondarily, I also want HTML output, because I want it to be easy to share code with people who don't have the native app. The example I posted is HTML, where the big parentheses are a creative use of CSS.
Joe Eagar 2024-03-20 04:00:01 You can get pretty far with the DOM editable document command api, though it's an enormous pain.
Fredrik 2024-03-20 04:02:47 I'll keep the HTML read-only and have the native app for editing, or let people use an ordinary plain text editor if they don't have the app. I've done editable DOM many times enough before to know that it's a never-ending pain. Editable DOM apps are always buggy, and it's never going to be fixed.
Andrew F 2024-03-20 15:04:57 Personally in this case I would lean toward more vertical (with good folding), even though in hand written code I tend more horizontal. Vertical seems like the safe choice, with no fine tuning necessary. But if you're already shouldering the burden of a separate UI for screen readers, it seems like it might not be a big lift on top of that to make the balance of horizontal or vertical space into a user setting? I mean, if you're feeling ambitious.
There's also a sort of middle ground, where the user chooses between vertical and horizontal formatters per syntax tree node, with a UI (and state management) akin to code folding. You could think of horizontal formatting as a folding state intermediate between fully vertical and fully hidden.
Fredrik 2024-03-20 15:22:47 Andrew F Yes, I'm feeling ambitious. The layout algorithm is a small enough part of the project that making it more complex is not a big deal. Personally I can't stand folding interfaces. I always end up setting them to the worst possible folding that gets the job done. I could as well keep my old automatic layout that is slightly better than the worst possible.
For top level navigation, there is a series of menus where the user selects a module, a class and then a method, similar to the Smalltalk browser. That replaces macro-folding . Once the user has selected a method, there is no more navigation, as the user likely wants to read the full source code of the selected method. It's here I'm trying to achieve a readable layout without implementing micro-folding .
Cameron Yick 2024-03-20 18:06:11 Hi @Fredrik , thanks for the response and the rationale about avoiding the path of author overriding the default for the user.
One idea I’ll offer is that the annotation is something the reader could offer bring to the table in their viewer. This is similar to how you can opt to fold/expand sections in VSCode for either bracketed code, or sections in markdown. A set of annotations is a filter, with unique filters for each situations. The name escapes me but I thought I saw a cool digital humanities project that used this “standoff annotation” technique to help people with doing close readings.
Jacob Zimmerman 2024-03-20 17:26:11 I want to build the backend of an as-bidirectional-as-possible spreadsheet/dataflow, does anyone have any favorite techniques?
I’d like to prefer a dataflow style solution over a constraint solver. I’ve been reading up on why this problem feels hard and its similarity to the “view update problem” in databases, I’m curious if there’s a widely accepted solution that I’m missing.
Jacob Zimmerman 2024-03-20 23:47:49 Thanks @Alessandro Warth, would you mind sharing any thoughts on how the project went with the constraint approach? I’m thinking right now about leaning on lenses and some semantics discussed in this slideshow “Weird World of Bi-Directional Programming” from Benjamin Pierce. Was there a particular reason you chose a constraint solver?
cis.upenn.edu/~bcpierce/papers/lenses-etapsslides.pdf
Dennis Hansen 2024-03-21 19:23:16 I've been enamored with the Propagator Model as a solution to this problem. The idea is cells don't just store values, but more broadly they store information about what the value could be (such as a set of potential values), and propagators are like functions that react to changes in any number of connected cells, do computation, and then updated dependent cells continuously by* 'merging' in information (like finding the intersection of a set to get closer to a solution). It's a bit abstract, but these networks can be used as general purpose constraint solvers/computers by reacting to changes to cells and propagating updates to converge on a solution/steady state (they can be structured so they always converge). Bonus is nodes are 'actors' in the sense they are autonomous, async, and thus can be distributed/run in paralle. Sussman and Radul have a paper in it- this is the best intro ive seen (youtube.com/watch?v=HB5TrK7A4pI), and there are some implementations of it in Haskel for example by this guy
Dennis Hansen 2024-03-21 19:26:33 Here's an visual: You can see how by wiring up an equation in both directions you can solve any variable given the other one*.
Dennis Hansen 2024-03-21 19:28:43 Lastly to add- this is not widely accepted- probably far from it. Just particularly interesting. Hope thats useful
Don Abrams 2024-03-21 21:28:01 Related, there's a great book on constraint theory by Friedman and Phan that digs into this kind of thing
avon 2024-03-22 04:37:53 @Dennis Hansen if you're into scheme and p2p networking at all there's this interesting experimental propagator implementation built using Spritely Goblins: gitlab.com/spritely/brainy
📝 spritely / Brainy · GitLab
A super research'y back-burner implementation of the propagator model. Ultra-pre-alpha! Still in the highly experimental stage! Not part of Spritely's...
William Taysom 2024-03-22 04:43:18 Hello, and welcome to one of my favorite topics. I'm so glad to hear the Propagator Model mentioned. One thing I've learned in spending... oh my... a decade plus on the topic is that you must integrate invalid states and a view model from the start. Then soon enough, you'll really want versioning.
Consider the simplest thing in a spreadsheet:
- Set
A1 = 24.0 . - Set
A2 = A1 * 9 / 5 + 32 . - Come back to edit A1. Type "x". What should happen to A2? For a usual spreadsheet, the answer is nothing. When active, a cell's state shouldn't propagate, so make that part of the model in the first place.
- Hit enter. We expect A2 to go funny in some way, ideally a way that points back to A1 as the source of the type error. An advantage of something like the propagator model is that you can wire your network as the basic level and then independently experiment with the semantics of error propagation.
What about versioning? Versioning is useful for collaboration, yes. And undo is essential for any non-trivial model that you can mess up. But a real potential is realized in having the system make a bunch of version of things and then combine them. For instance, make a bunch of copies of A1 and A2. Vary A1 and chart how it affects A2. So instead of having separate looping constructs, just allow for clones/copies of the parts of the model.
And if you make time first-class, instead of distinguishing between a clone and a copy, you can choose to either modify the original before or after copies were made to get a similar effect. An advantage is that you now have a well-defined semantics for conflicts when an embellishment of a clone is incompatible with a change to the original. You can pinpoint: this operation no longer works.
Jacob Zimmerman 2024-03-25 19:15:30 Propagator model seems really interesting, thanks @Dennis Hansen @Don Abrams @avon @William Taysom! I’ll update when further questions come up.
Duncan Cragg 2024-03-24 10:36:57 Duncan Cragg 2024-03-24 10:44:02 .. or if commercial, please be technically interesting or different in some way, rather than filling the spreadsheet with marketing guff!
Duncan Cragg 2024-03-24 10:55:16 I've added a new row to allow people (like me!) to be able to claim they've created a new programming model paradigm.
Duncan Cragg 2024-03-24 14:57:24 Hey there Ivan Reese , it seems like I should pass ownership of this over to you and the rest of The Management, what do you think? 🤗
Kartik Agaram 2024-03-24 16:32:08 I'd be happy to take it over, but be warned I will delete Dynamicland and its ilk from it if I do 😄 I might also deprioritize/archive many of the columns whose owners aren't active here anymore, since I see the sheet as a call for collaboration with people here.
(I'm stating my opinions strongly for contrast, but I'd be happy to be persuaded about individual decisions if people here feel strongly. But Dynamicland has got to go. There's no action there anyone can take, and it dilutes the sheet.)
Duncan Cragg 2024-03-24 16:50:05 Dynamicland is the only one I'd keep. Yours would be first for the axe! 😂
Kartik Agaram 2024-03-24 16:50:38 Yeah, if you have a vision you gotta stick around for it. Nobody else will do it for you.
There is no exit.
Duncan Cragg 2024-03-24 16:51:14 Seriously though, you chose the one project I would never want to see deleted, other than mine of course. Why the hating-on?
Kartik Agaram 2024-03-24 16:53:54 Oh I love Dynamicland! How could I not?!
It has to do with what the goal for the sheet is. I've said this to you a few years ago. If you think the goal is to showcase the best work in the vein of this forum, Dynamicland and Dynabook make it in first.
But if the goal is to foster collaboration, they're dead weight.
Now if somebody were to try to recreate them, that would be top of the list again.
I wouldn't try to do both sides in a single sheet, that feels muddy to me.
Kartik Agaram 2024-03-24 16:55:35 Oh interesting! 🤔 That somehow was never clear to me until now.
Kartik Agaram 2024-03-24 16:57:28 Many of the rows don't make sense for Dynamicland. It shouldn't matter how many people work on it, or whether it's active or not.
I'll reiterate that you should add more from the past then. Dynabook, Boxer. Ivan's Visual Programming Codex has more projects like that.
Hmm, arguably the VPCodex does a great job already of comparison and inspiration.
Duncan Cragg 2024-03-24 16:59:40 Well it was meant to be people still alive and kickin' and mostly for those either on FoC or those who, if they weren't such big fish, would be here! Like Obenauer, and I suppose Kay maybe, and Victor of course
Duncan Cragg 2024-03-24 17:00:29 Current live projects you look around as a FoCcEr and get inspiration from
Kartik Agaram 2024-03-24 17:04:07 Boxer folks are alive and kicking. The project is even getting restarted, I heard somewhere..
Kartik Agaram 2024-03-24 17:11:24 Another axis to consider here is the audience. If you care about projects that are personally inspiring, that will vary from person to person. I'd make that a page on your website that you update and nobody else can. Pretty low-maintenance.
Alex McLean 2024-03-24 17:36:00 I'm really enjoying collaborating with dynamicland, and according to their current website, 2022 was earmarked for 'dynamicland meets the world'. Delayed somewhat, I guess mainly by the pandemic..
Kartik Agaram 2024-03-24 17:37:40 Oh I'd love to hear more Alex. Perhaps share resources in a new thread? Sorry Duncan I've destroyed this thread.. 😕
Alex McLean 2024-03-24 17:38:01 If dynamicland is no longer active, then someone forgot to tell Bret and Luke..
Kartik Agaram 2024-03-24 17:39:35 My perception is it's not taking input in the same way an online community is. There's a pretty fundamental impedance mismatch.
Kartik Agaram 2024-03-24 17:45:46 Absolutely legitimate trade-off to make. But there are things they're trading off. And among them is being on "my" spreadsheet.
Alex McLean 2024-03-24 18:00:47 Personally I've got loads out of collaborating with Luke, although I am very much a free/open source person myself. I think the early stages of development of a creative idea is a special time that should be somewhat protected, and I guess they're in it for the long haul. I'm also sympathetic to the idea that open source techbro culture isn't a panacea, and their pre-pandemic focus on in-person collaboration and continued focus on long-haul in-the-community nonprofit development is really interesting.. plus their new website will share a lot.
Alex McLean 2024-03-24 18:02:31 Anyway not wanting to speak on their behalf. Clearly it doesn't belong on a list of free/open source licensed software.
Konrad Hinsen 2024-03-25 06:59:55 Strong agree with @Alex McLean that we need to experiment with new forms of collaboration. Open Source was a first step out of the industrial-capitalist mindset. We need to take more steps.
For the project list, that means thinking harder about what should and what should not be in it. Only projects from people active in our community? Only Open Source projects? I'd tone down the latter to "only projects that we can learn from", which requires less openness than Open Source.
Alex McLean 2024-03-25 10:29:10 Yes, acknowledging that the future of programming might well need to be defined outside any current community of programmers. I think that's Bret Victor's position which might be why there seems to be some animosity towards dynamicland here..
Duncan Cragg 2024-03-25 11:12:28 I think the main thing wrong with Dynamicland is its core, local-only, in-person philosophy! I obviously get the whole "handling real objects and interacting in person with people right next to you" idea, but to specifically cut out internet-based XR* from the discussion (and derived from that, or on top of that, having no normal internet presence and not being more open to non-in-person discussion of the ideas) seems very narrow-minded.
(* AR and VR)
Alex McLean 2024-03-25 11:56:23 It's been pretty strange mostly working in Realtalk with only myself in the room, but of course the pandemic necessitated a shift of focus on collaboration over the internet. The tables are nicely linked.
Duncan Cragg 2024-03-25 12:02:00 Oh, I didn't realise it uses this "internet" thing now! I didn't see anything about that. What "tables" - physical ones or database ones?
Duncan Cragg 2024-03-25 12:15:27 Ha, right, thanks! So, is there any info anywhere online where I can read about or see this collab via linking of tables over the internet? It does sound like a significant deviation from the philosophy, and you hint that it's been happening since 2020-ish, right?
Alex McLean 2024-03-25 12:19:47 Not as far as I know, maybe there'll be something on the new website
Kartik Agaram 2024-03-25 16:21:50 Jeez I have zero animosity towards Dynamicland! Saying I wouldn't take a bicycle into the pool doesn't come from animosity towards bicycles.
Ivan Reese 2024-03-25 16:31:26 I feel like what's actually needed is a project wiki, not a spreadsheet, and then we can tag a project as "by a member" whenever the person working on it is active here. I keep meaning to turn the codex into this...
Ivan Reese 2024-03-25 16:32:14 I think the #1 thing that stops me is not having a good way to spin up something world-writable that has a modicum of abuse resistance.
Kartik Agaram 2024-03-25 16:43:57 That's a good point. I think all my comments here are through the lens of a spreadsheet, where space is a constraint and the projects are inherently ordered. A wiki would break out of that shackle.
