Keep It Concrete
I’m reading through LeviathanCoding’s Pixel Art Editor trying to learn p5.js. What’s great about it is you see everything on the screen at once. There’s a canvas for your drawing, a palette of colors you can scroll through and select, an erase “color”, and buttons for saving/uploading/configuring. That’s it.
Mapping between what I can see and what the code does is important. Code is abstract. The first thing I do when reading someone else’s code is orient myself. What does the program do and where does that action happen in the code? I can then begin to follow the thread. This is why context switches hurt programmers so much: they’ve drawn the map between reality and code in their minds and if anything else crowds in there they’ll lose the map.
Drawing that map is hard when you’re a newcomer to programming. Last winter I guided my kids through some Arduino projects. They could look at a diagram and wire it up no problem. When it came to write the code, though, they had to copy it directly from the book. Each character had significance. It’s hard to hone in on which code makes the light blink when you’re wondering which keys to press to make the
# character and what
<stdio.h> even is.
In this case, as I scrolled through
script.js, I saw a
setup() function, which calls
upd(). There’s also a
draw() function that looks a lot like
upd(). Reading through those functions, I see the code to draw the editor, the erase button, and the color palette. It seems LeviathanCoding stores the state of the picture as various symbols in a string. Each symbol maps to a color. In fact, the first 160 lines of
setup.js contain a mapping from symbol to color. The basic idea seems to be: draw the canvas and the palette, then draw the picture so far.
I’m familiar enough with graphics frameworks to know that there’s a
draw() function that will get called repeatedly. But it still really helped that I look at the canvas and various buttons and see where they’re drawn in the code. I have spent many hours of my life searching through code for a button, and then trying to figure out which other code gets called when you press the button. Sometimes my search did not end successfully!
Abstraction is powerful. It’s high-leverage. Yet every person coming to your project, whether to contribute or just figure out how it works, will come with a list of concrete questions. What happens first? What happens next? If I press this, what happens?
Making programming more accessible means making it so people can ask and answer those questions all on their own.