I'm suddenly bothered by the fact that code comments are always the same size. Sure, I've seen some people play with rich text in their code editor, applying bold or font size the same way you apply color. Atom's CSS was great. But that's outside the code. Your font size tweaks aren't going in the repo. (That'd be a tabs vs spaces fight for the ages!) But… what if I want to leave a little pocketbook tucked into the back flap of a function? Unobtrusive. It's there as a reference when you need it. Within, you can fully explain why things are the way they are. You can talk about the history of this code. It's the sort of stuff that you'd put into a wiki, or spread across a series of commit messages — but it's right there in the codebase, but it's tiny and off to the side. There when you need it, easy to ignore when you don't. Makes me wonder about other ways that being able to choose the size of representation in a program — independently from typical size units of code (ie: lines) — could be useful. Eg: at the main entry point of a well-factored complex program, where you're dispatching off to various other subsystems, things deserve to be quite large. Makes me wonder about other things that ought to live inside the codebase. To start: every feature of Github? (Consider that it serves their interests that, say, the discussion around an issue or PR lives on their cloud, not in the repo.)

🫶 Yes yes yes! A lot to this. I have a silly shell script I use to sort of support this. It allows me to attach arbitrary files to any other files and open them in concert. I use this for comments, scratch spaces, experiments and generally muddying the waters. I started trying to make my own editor to support this workflow, but found that everything I wanted already existed within the OS itself, so, instead, tried to leverage those and not re-create the wheel (also, I'm allowed to run this on my work computer where I use it the most 😆)

Re: @Ivan Reese

The editor experience is…uneven. For the most part I rely on my memory to know if there are existing moons for a given file, but I also have a command to list available moons by given file name. Eg, I can check if app dot tee es has any moons, and then open em or not. It’s not super useful for folks other than me, these days. I also tend to do things with window systems that folks find alarming (aka, never a tab, a million windows) I manually arrange moons near or around files, usually in smaller, as close to square as I can get, windows.

(aka, never a tab, a million windows)

A, a citizen of Siracusa county :)

Tax paying, flag waving, patriot of it, yes.

Swift/Xcode has some kinda Markdown-formatted comments thing. That’s not specifically about size, but it’s related, right? Rich formatting embedded into the source-of-truth code?

I’ve been thinking that we should have and use more formatting (fonts, sizes, weights, layout, etc.) in code. Why shouldn’t my code look as good as a professionally typeset manuscript? Has anyone tried this?

I use acme, a text editor from plan9 pretty much daily. By default it uses proportional fonts. Not exactly the same since everything is the same text weight, but, I find it nice for the most part. I also write a lot of apl. The dyalog interpreter uses sort of proportional fonts for the glyphs. But there there’s a pretty stark aesthetic distinction between code and everything that isn’t code.

The visual design needs of prose and code are very different I think, applying similar tools without analysing those differences feels like it would quickly become counter-productive imo

I feel — though I’ve not explored the idea much — that formatting could indicate some of the semantics of a program in place of some of the symbols we currently use. For instance, indicate a function declaration by the name of the function being on its own line in larger, bolder text. I’m not sure how far this goes. It does seem to end with some sort of structured editor if you want to edit code with formatting like that. Or, maybe just having a way to take some source code and typeset it for easier reading? (If it would actually be easier instead of frivolous.)

There are a couple entwined questions here. One is varying prominence of comments and (presumably other language features). The other is traditional text formatting for code. I like the idea of supporting different types of documentation at the language level, and potentially different display, if it's standardized, or if I can uniformly configure it in my editor. For general formatting, the conventional wisdom is already to enforce most formatting questions via linter. I think adding more degrees of freedom will make things worse for all but the most artisanal coders.

Appreciate all the comments! If you, humble reader, find yourself thinking "not sure if that'd fit well with the tools I use, or my team culture, or the broader ecosystem of my PL", then by all means deeply consider the reasons that it won't work. If that leads you to a realization about how to make programming better with a few minor tweaks on the status quo, awesome! But also—if you'll allow yourself—indulge in a bit of wild speculation about how things could be radically different. For instance: I arrived at this "hey, why no sense of scale?" thought by actually imagining tucking a booklet into the back pocket of a function. I picture the booklet as being about the size of my hand, maybe 50 pages with a nice flat binding, and the function is something made out of cloth and metal and it's about the size of a large dog. It feels a bit like remembering a dream — the details don't need to be clear, they just need to motivate me to ask "why?" about something I've taken for granted for * checks watch * about 20 years now.

On the topic of

TBD: FIX: ...

I started using a couple functions named

e.g. n.b.

for this purpose. Tooling can find them, but their argument can be anything.

e.g.

, of course, is almost always an inline example, but may refer to a file, url, or hashtag. While it may make sense to change how things look, I imagine many of us remember the early days of desktop publishing, 3D borders in GUIs, circus-inspired web pages, etc. The goal is to communicate meaning and intent clearly, in context, but also let people find more information as needed or desired. So, rather than text size, what if this content became links, maybe with a preview popup? Things can be smaller, but still a paragraph long, which makes them either hard to read or take up so much space that you lose more active content. What I try to do is minimize the size of the comment content, though sometimes I still do entire paras and have 5:1 comments to code by line.

I think LP would have been better served by getting rid of the whole typographical angle: http://akkartik.name/post/literate-programming This isn't to say typography doesn't matter. I love OP. I just consider any connection to LP to be a red herring that will lead you astray. LP's notion of typography was much weaker than Ivan's vision. This matters because I think this is a misguided question:

Why shouldn’t my code look as good as a professionally typeset manuscript?

Why should code look like manuscript? The use case and needs are very different. Code is fundamentally non-linear. I mean, to the extent that we have zero typography in code, sure, anything would be an improvement. But I think it would quickly hit diminishing returns. It would be a strategic dead end. The typographic needs of code need to be rethought from scratch.

cough, cough https://px23.clerk.vision

a little pocketbook tucked into the back flap of a function?

Reminds me of some paper I've seen attaching hand-written ink annotations to code. don't remember the specific paper, but found now several on Beryl Plimmer's publications, sounds like a good starting point... (I have to question the long-term accuracy of anything you can't grep, but actually handwriting recognition might mean you can, and anyway there is interesting value in enabling the kind illustrations we tend to draw on whiteboards but rarely commit.) Varying font size go nicely with zooming! Code Canvas tried quite a lot of that. Imperfect aesthetics, but some interesting gradual-reveal functionality 👍 https://eaglemode.sourceforge.net/ file manager does quite unusual UI tricks with zooming and font sizes – e.g. instead of tooltips, UI elements (buttons etc) documentation is engraved right on them in tiny font. See "project philosophy" there. And https://museapp.com/. Prototyping tips: (1) Emacs supports varying fonts. The poster child is latex but you can apply it to any kind of syntax-highlight. Plus various support for folding. (2) on the web, CodeMirror.

Common writing advice says to delay styling until the writing is done. Most code is never finished; it's merely released, to be edited again soon.

Of course emacs can do it. 😄 I'd imagine it gets progressively harder to do "fancier" layouts, though — some because of the limitations of the language's syntax, and some because of emac's limitations (uh, if it has any…). Out of curiosity, can comments be formatted as some sort of aside or margin notes in emacs?

What ways can we devise to communicate that structure more effectively to our brains?

Size, shape, space, similarity, sequence, segment, sound… .…smell, saturation, story, sitar, situation… …sauté, Solar, seat, seal, satire, superspirituality…

I think structure applies in-the-small as well as the large. Kind of like every book has beginning/middle/end as does each section, chapter, paragraph, and down to the sentence. What is the story a piece of software tells to us, as narrative-oriented creatures? I also like to think about https://dictionary.cambridge.org/grammar/british-grammar/adjectives-order, as sometimes inheritance does it completely in reverse order. We get it, because we know the attributes have to apply to something, but there's no reason you couldn't say "give me a big red button at 100x200" instead of "at 100x200 button red 150x30`.

The Jupyter/Colab experience is so good that if I want to demonstrate some Prolog alongside an explanation I'll often do it inside Python just to use Jupyter. SWISH just isn't quite the same. Comments seem like a smaller version of the same problem. Also very relevant for Rules as Code, where segments of code are supposed to correspond to segments of text. Blawx uses the text as a navigation tree, and puts the code in a different window. But the Jupyter approach makes a LOT of sense. A jupyter-like interface with Blawx for code, WYSIWYG XML for law, and Markdown for comments would be fire.

Happy to see people exploring these ideas. The ability to have richer ways of thinking about textual programs is one of the reasons I'm working on my own editor. I always want to leave the that little booklet of context. I always want to detail the history of code. I want to take notes, some I want to publish for the team, others for myself. I want to make a tour of the codebase for new contributors, one that exercises bits of the actual code. I want a live demo of that exponential backoff algorithm. I want an interactive integration test complete with live architecture diagram of the running system. We haven't even gotten close to unlocking what we can do with textual based code. Our integrated development environments don't integrate much.

Having a "try demo" button next to a function that does some kinda visualization of how it works would be 🔥

For history of a codebase I go spelunking in version control. Write good commit messages, people! You want features to be easy to delete, and they'll only be easy to delete if (Chesterton's Fence) we are confident we understand why they exist in the first place.

But IRL I wonder if I would feel justified in taking the time to add those kinds of things in the kind of work scenarios I've always been in. Too much time pressure, too hard to justify to stakeholders why I'm making such fun documentation.

(Sorry to go all #present-company)

Yeah, I think the present company approach leaves a lot to be desired. I'm almost never interested in the actual history of a project, but in an idealized, rational reconstruction of the history. Version control doesn't actually tell use why things exist. If well written, it might contain the public reasons people are willing to state why they did something. But there is always more to it than that. At the simplest, least contentious level, they might just write something that doesn't make sense to me personally. They may conceptualize things in a way I don't. What I need is to translate that history into terms that I can understand. Where do I record that? Perhaps parts A and B were made at different times, but for my purposes it is more useful to consider them as a whole, how can represent this? More contentiously, there is always more to the history than what is recorded in version control. Easy examples, how does version control correlate to changes outside the code? RM used to refer to the Regional Manager, but now RM means Relationship Manager, which is what the code calls a CM (Customer Manager). Knowing the version control story doesn't help me know this story. Less easy example, we often don't tell the whole story in source control. Why did we choose framework X, because framework Y has a bad rep at this company because a team failed with it. Why don't we just make an obvious change to module A, because person B will get mad. Why is this test written differently? Because Josh thought it was a good idea, because it was easy to write, but he never had to go back and modify them. We all told him they were awful to modify, he didn't listen. Then we made sure he got a ticket where he'd have to modify his own test. Now, he realizes how wrong he was, but is too lazy to fix it. (Definitely not a real example...) None of this is in the version control history. But all of it matters for how we approach our code.

version control + documentary film crew?

@Grant Forrest Why justify it? We are hired to do what is right, not what we are told. We have the knowledge and expertise to make the right tradeoffs. We ought to care about our craft and do things that are not strictly necessary. If you want a personal justification for it that is couched in business terms, programmer happiness matters because turn-over is one of the most expensive things a company can deal with. But I think we need to get out of this scarcity mindset. We can make time for the things we care about. We can have good codebases we like to work on. We can do all of this and still meet stakeholder expectations. It just requires a very consciously chosen, particular way of working. It requires us to assert our expertise, to take ownership of the programming aspects of the work and not simply do what we are told.

I definitely do try to focus on DX as much as I can, especially as I get more senior and need to set an example in the organization. I think I may have misplaced the origin of my anxiety as I was responding, not sure why. Recently I started a new role at a company which struggled a bit with frontend, my expertise. I felt a lot of pressure to balance digging in and providing great learning resources on particular issues, with the sheer volume of problem areas which needed my attention. It took hours or even days to provide high-quality learning material. Prioritization was hard, even though my manager was really supportive of my efforts. My observation on general practice is that early on, the codebase is extremely volatile because the product is volatile. Ideally, huge swaths of that code will be deleted or refactored multiple times within the year, because to not do that implies your system isn't evolving with the knowledge you're gaining about the problem. But this is also the time when culture is formed, and when it's really important to put those practices into place... What I'm trying to figure out is how far to push it, how much investment to make into documenting and polishing things which may not survive the month. Maybe one problem is that when we delete code (which I very much want to do) all that work disappears from view.

Hmm. Git already stores them 👻 but editors dont visualize them. Q: how do you know/mark which tombstones are interesting? I've seen projects that comment out code, or move code to Attic/ dir before fully deleting.

@Jimmy Miller it might be worth stating (refreshing) our assumptions about what "future of coding" means 🙂 • On the one hand, people will always have unstated reasons for doing something. Changing that feels out of scope for "future of coding". • On the other hand, reducing the friction to write down the reasons you are willing to state seems in scope. I think any improvement in this area also would be of huge benefit, far more than any typographical changes. • I don't just use version control, I use version control along with all the other tools the project/team/culture uses. It's always going to be an exercise in forensics/archeology, changing that feels out of scope. A totalizing tool that tries to capture everything seems infeasible. To put it another way, the fact that A and B happened at different times by different people (with different understandings) seems essential to understanding the interaction between them. That will never change, changing that feels out of scope.

@Grant Forrest I like that way of thinking about it much better. These are difficult balances to strike. Pragmatically, I'd say in early phases of projects, its much more important to establish common values and understanding among the people writing the code than it is to create documentation. Agreement on one value is worth 100 "best practices". I worked at a consultancy where we pumped out greenfield frontends at a crazy pace. These were all initial versions/prototypes for a customer made in a month or two. Usually ended up being about 30k lines of code. We spent most of our time coming to agreements on what we want to explore in this project. What ideas do we want expressed in this codebase? What do we want to avoid? Getting on the same page there was more valuable than documenting what the codebase was. Jumping into a codebase you hadn't touch was much easier when you understood the ideas behind it.

Jimmy's examples run a gamut IMO from "yeah, it would be really great to have that documented" to "no tool can save you from crummy coworkers :,)" I particularly like the idea of runnable demos as part of the documentation. It reminds me of Python doctests, but potentially way cooler.

@Grant Forrest @Jimmy Miller The goal of tools should be to make it cheaper to do the right thing so you don't need to justify it to others. The need to justify to others won't go away unless you own your code. (Not to be confused with "exercising ownership" over code, a related and also useful idea.)

this is not a shit post: what if the future of coding is the friends we made on the way? meaning, what if the future of coding, sort of how DynamicLand suggests, is waaaaay less about technical things, and more a new way of approaching code in community/communication with a team? I think Naur was sort of circling this thought

@Kartik Agaram I think I may have assumed too much in my post. I agree that we can't change that people have unstated reasons. Nor can we capture everything. My point was that our current tools seem (to me) to not account for this fact. Version control is an immutable history. The history I care about isn't. It is an opinionated, shifting history. Not because what actually happened changed, but because my uses of that raw stuff change. This doesn't mean capturing everything. In fact it means precisely not capturing everything. What we need are tools that let us form our own views of history. That let us create new histories but that are rooted in our codebases, not external to them. I don't see tools doing that.

https://storybook.js.org/ is a quite successful docs-with-runnable demos thing. (A bit easier when the subject matter is UI components.)

@Jimmy Miller Agreed! FYI, here's the tool I created out of frustration with using immutable version control for history: http://akkartik.name/post/wart-layers. But an immutable append-only log is also a key tool for reconstructing history for ourselves. @Eli Mellen This might be surprising, but the whole goal of Mu was communication. In particular, to record why for every single assumption in a system, working up from bedrock. (I stopped working on it because I realized the key places where this is impossible.)

what if the future of coding is the friends we made on the way?

I twitted that out for tools for thought. But that one works better because of the double entendre. I do think the culture is a huge part of the FOC mentality. It's why I'm personally not interested in just being a press release venue for startups building tools. We have to take a wholistic view of the way technology relates to all the aspects of the world and our life. We have to think about the ways in which the technology we makes impact people. When building new technology, it is less interesting to me what "problem it solves" and more interesting what it says. What's its viewpoint? How does it change the way people approach life and tech? That's why I'm interested in reading the papers we read. These are people thinking about this stuff, thinking about what we ought to make, and what it means. Not simply building a tool so a VC can get a bigger return on investment. We already have lots of talk about those companies and what they are doing, let's do something different.

loving this! these days I mostly work in product which means a weird thing in the government context where I work, but, it allows me the ability to manage teams and set priorities — I often frame this work, personally, in a FoC context — “okay, we normally do it this way, but what falls out of that way? what can we do different?” — I don’t have like wicked cogent thoughts about it, or a secret sauce, but I’ve found there is sort of a super power to be had by not being an asshole, and knowing how to bridge the technical and interpersonal. Many of the papers you all have shared through FoC I’ve found really insightful for this sort of approach, even if not directly about “management.” Meanwhile, everything I’ve ever read about management, proper, is so squarely situated within a capitalist context that its priorities are mostly divergent from what I understand to be the goal of FoC

@Kartik Agaram yeah me voicing "it's hard to prioritize this kind of work" is definitely meant to direct toward, "can we make these things not only possible, but much easier?" One thing I find is underestimated in docs/examples is upkeep. I can get people to adopt Storybook but I can't get them to keep it up to date with changes. If we could make a system which captures the intent of your documentation or example and helps update it as the code changes, perhaps that would help make the work feel more worthwhile over the long term.

Just wanted to add to the original thought the style of comments, code and programs: I think we can draw inspiration from both books and maps. Books (also think dictionaries, cook books, …) mix different kinds of text (prose, informative, technical, …) and make use of different fonts and styles to communicate the kind of text. In code editors, the main work horse is color – syntax highlighting. But there’s more potential. Books also use margins to display contextual information that is optional to read. This would totally make sense for code comments and we’ve sometimes seen documentation sites displaying a two column layout with code on one side and prose on the other side. Books also have an index, glossary, introduction, etc. – pages that have a dedicated layout. These are designed to provide overview and navigation. Unfortunately, our code often lives in files and folders, only displayed in trees/lists, alphabetically sorted. Spatial maps would make much more sense so that code can be organized by other criteria than just file name. Traditional maps also make use of a ton of typographic styles to distringuish between landmarks, cities, countries, rivers, mountains, … and interactive maps can even control the level of detail that is shown depending on the zoom level. I totally see the lack of formatting in editors. In most themes, comments are muted / less visible. But considering that they are meant to be read (?) it makes no sense to make them less legible. I think there should almost be a reader mode that makes it easier to read the comments and dim down the code instead. I’m not sure if authors should have control over the styling, but I think that there’s more information about the structure and meaning of code that could be visually encoded.