FWIW - here’s how I think about it... You are programming a MACHINE. Every bit of syntax has to DO something (have a meaning). [The meaning of comments is “to be ignored by the machine”. A lot of other syntactic baubles have that same meaning - e.g. stick people and clouds]. What does it mean to connect a wire to a word? What happens if you connect that same wire to a different word?

One issue I have with comments is that they are monochromatic / monotonous. Not many programming environments let you be expressive with your comments. You can't distinguish a "what" comment from a "why" comment by any means other than verbose writing or pidgin syntax. I'm big on finding ways for person-to-person expression within a codebase to be a lot richer.

I would like to have better tools for annotating code with its relationships to legal text that it models. I don't need there to be a visual line (though it might not hurt), but I do need a convenient way to create an "annotation" which includes disjoint segments of text, where annotations can overlap one another, and can be linked from symbols in the code, so that when I mouse-over the relevant code, the linked sections of text are highlighted, or something. There's a lot of room to improve the way code and text relate to each other. If you could even implement something like that inside Jupyter I think it would be illustrative.

@Ivan Reese oh oh oh! I dig this idea a lot! I’ve been playing with a way to allow text/files to exist in relation to one another — at first I thought about doing this through a bespoke editor, but realized I didn’t wanna reinvent that particular wheel — I was aiming someplace between text files…I didn’t care about how they were generated. I care about finding a way to make multiple text files touch and look at each other and reference each other. My mental model for this is something like the talmud, where you’ve got a core text (maybe your executable program) but then all these layers of commentary around it, in orbit. The commentary is held in place by the core text, but may not actually only be about that core text, it is also in context and talking to other commentaries and other pieces of text that are core to other stuff. …sorta rabbit hole around “all text is hypertext” and pleading with a tool to let it happen.

I use 3 different colors for comments, though I hadn't thought to distinguish what from why comments: https://news.ycombinator.com/item?id=21665105#21665366

Agreed: coments suck. The Goal should be to never need to write comments. FWIW: my solution is to begin with software components. A Component is asynchronous and owns input ports (green circles) and output ports (yellow circles) and may contain other Components or be attached (via the ports and wires) to other Components. My syntax for a Component is a rectangle (as drawn, say, on a physical whiteboard on a wall). Synchronous code cannot be componentized (easily), so I mark synchronous code by putting it into red-coloured rectangles and dropping the red rectangles inside of non-red rectangles (async Components). There are two separable issues - (1) explaining to the machine (aka “computer”) what to do and (2) explaining to other humans why 1 was written the way it was. Frothing aside: operating system processes are simply Greenspun’s 10th Rule bloatware versions of Components. Code libraries are always red-boxed. Lisp 1.5 anonymous functions are less bloatware-y versions of the basic idea. Closures are optimized anonymous functions (optimized along exactly one axis (i.e. the fervent, religious belief that “efficiency” can mean only one thing)). So-called “programming languages” are 1950s IDEs for explaining to stupid machines what to do. Later, these old-fashioned IDEs were given double-duty by conflating the issues of communicating with dumb machines and of communicating with other humans. I find it more fruitful to fully separate these 2 issues, then to drape “syntax” (sugar sprinkles) over the manifestations to provide less-glaring results that cover both issues (syntax, to me is: hybrid diagrams (such as Excalidraw, draw.io, SVG, etc. that encompass text), i.e. text-based programs are but a subset of less-textual programs)

@Ivan Reese I would love to see this!

@Ivan Reese You would need a reasonably flexible graphical support for that 🙂

For a while, NeXT’s gcc supported RTF input files. Fun times….