I was just pair programming with one of my team members and we were trying to reason about the implementation of a particular code snippet, but we kept getting bogged down by the actual implementation details rather than the “high level” process design (bad/outdated names, obtuse API calls, all the usual suspects). Out of sheer frustration, I copied the snippet (~100 loc) into a blank text document, replaced all the variable names with sentences describing what they contain, replaced all function calls with a description of what the function does and the data it operates on, and then sent it back. I left in syntax like variable declarations, return statements, array destructuring operations and array methods (map, filter, etc). Within 5 minutes we were able to have a reasonably productive conversation about the process and how we could refactor it, and it just seemed like it really “clicked” for both of us. It was the closest experience I’ve come to in terms of having a “shared mental model”. So I’m curious: is there anyone in this group working on tools for writing and reasoning about pseudocode?

We’re working on making those pseudocode lines into the actual code 🙂

I'm a big fan of: write the pseudocode bullets, leave the pseudocode bullets

Why does it have to be pseudocode? I believe what you want is a narrative about the code.

@ibdknox That seems like the common-sense approach: I suppose I tend to think of pseudocode less as a “programming” medium where it would eventually (either rapidly or over time) get crystallized into a working implementation, and more as an “rapid communication medium” where you could dip in, sketch out an idea, and get others on the same page. It seems to me like the difference between using Photoshop and using a whiteboard to have a high-level design conversation: the ephemeral nature of a whiteboard conversation allow for rapid iteration and communication, but it’s not like I would ever want to take that whiteboard drawing and paste it into Photoshop to try and tweak it. Similarly, I wouldn’t want to stand around Photoshop talking about design ideas because the tool is simply too “heavy” for the task. @Chris G “comment-oriented programming” is something I do frequently, I keep going back to this thread from a few months ago: https://futureofcoding.slack.com/archives/C5T9GPWFL/p1586957244445200. @Tudor Girba I think that’s a nice way to characterize it: perhaps the term “pseudocode” is a bit loaded in this context…

I think that difference largely comes from the ability to be much more implicit on a white board than in photoshop. In some sense you’re painting in broad strokes and then filling in the detail later. It’s possible to build a programming system that enables a similar flow. It just requires allowing for implication and ambiguity so you can layout the idea before fully realizing it. That’s a research-level problem, but our approach seems to be pretty promising so far. 🙂

Couldn’t help but connect this thread to this other one about Christopher Alexander and pattern languages: https://futureofcoding.slack.com/archives/C5T9GPWFL/p1604741927363000?thread_ts=1603601936.277700&channel=C5T9GPWFL&message_ts=1604741927.363000

if it’s not confidential i would love to see the text document from a user research perspective

@Tudor Girba What's the difference between pseduocode and narrative about the code? That sounds like an interesting distinction, but I'm not sure I know what it means.

@Garth Goldwater here's an excerpt of the pseudocode we were exchanging: unfortunately the rest is proprietary, but this should give you the gist. for context, the shorthand

selector

here refers to

createSelector

from the Reselect library

warranties with pricing = selector(
  unrated warranties,
  rated oem warranties,
  rated partner warranties,
  () => {
    const warranties with pricing = [
      ...unrated warranties.map(calculate pricing for unrated warranty)
      ...rated oem warranties.map(calculate pricing for rated oem warranty)
      ...rated partner warranties.map(calculate pricing for rated partner warranty)
    ];
    
    return warranties with pricing
  }
);

warranties for menu = selector(
  warranties with pricing,
  menu columns,
  () => {
    const warranties without menu column = warranties with pricing.filter(warranty is not in a menu column)
    return menu_columns.map(current menu column => {
      const warranties in current column = warranties with pricing.filter(warranty is in (current menu column))
      return [
        ...warranties without menu column,
        ...warranties in current column
      ];
    });
  }
);

warranties for desk = selector(
  warranties with pricing,
  () => {
    const warranties for desk = warranties with pricing.filter(warranty is not in a menu column);
    return warranties for desk;
  }
);