Friendly Error Fellowship

Meet the P5 Maker:Sue

Fri, 29 Apr 2016 00:00:00 +0000

Twitter Handle: @deathbearbrown Occupation: Open Web Developer What she makes with p5: Experimental Art

Sue learned about p5 from her colleague at Bocoup, a open web consultancy. Her colleague shared an experimental drawing application (making a realistic pencil stroke) at a staff show and tell. Sue was inspired and embarked on her own tinkering journey. As an Engineer, she came to p5 with quite a bit of past coding experience. In fact, Sue used processing.js when she was in graduate school. At that time she was interested in manipulating datasets and crafting data visualizations.

What do you like about p5?

Pretty much all of my processing code from back in the day works in p5! I currently use it for experimental art stuff. I like doing stuff with repetitive algorithms and fractals and then trying to modify it … and modify it until it gets really bizarre and interesting.” Sue often tinkers with opacity and different variables to achieve the effect that she desires.

What are your barriers to entry?

Random and random seed - while it’s a completely normal thing in other programming languages. It’s baffling to me and it’s baffling to anyone who is using this. I have a hard time figuring out how to structure my code so that what I think will happen will happen.

Have you used any other introductory creative coding tools?

2js and 3js a bunch. 2js is a 2d implementation that 3js is (a google experiment) - you can make shapes, animations and effects. I don’t use 2js because I was getting annoyed with the performance - the things that I was doing were crashing the browser. When I got bored with 3js I just went directly to canvas.

What are your goals for using p5?

I have an art project that i want to do. I guess getting through each step of that, and learning how to make that possible. # How are you going about learning? I’ve been doing “Fractal Fridays.” I got the algorithm from wikipedia and then go on to mathoverflow to convert the formula. A lot of it was really basic algebra. I got into fractals because they look cool. I had taken a course in computer graphics - the math that goes into that. That helped me to see that math could be fun. I realized that I liked learning math through graphics. Everything that I know about p5, I know because I’m converting it from Processing. Ill convert it and then run it, if it breaks, I go to the p5 documentation to see if anything has changed or been renamed.

I like to see inspiring things made with p5, but I need them to be modifiable so I can play with it.

How do you handle receiving error messages?

If it’s an error message that makes no sense to me then I copy, paste and google - I usually end up looking on stack overflow. If it’s a situation where my code is just breaking - then I’ll add breakpoints in my code to see where it fails. I read error messages all of the time. I can’t even think of an error message in p5.

Most of my problems with p5 aren’t errors. It’s working fine but it’s just not doing the thing that I want it to do.

Here are some projects that Sue has made with P5:

I didn't set randomSeed() pic.twitter.com/f6LzlQKR14
— You just got Sue'd (@deathbearbrown) February 19, 2016

Peer Learning with P5

Fri, 15 Apr 2016 00:00:00 +0000

I have always been a tinkerer, I love to craft–Pinterest is my jam, but with coding I’ve really never felt like I have been able to get to a place where I could tinker. Atul convinced me to apply for this fellowship because it would give me a chance to experiment and learn p5 in order to tinker with code in a lightweight way, so that we could help other designers and artists who, like me, might be enthusiastic but just a bit overwhelmed with code.

The way that I approached learning p5 was pretty simple. I started by watching Dan Shiffman’s videos on YouTube. They are great tutorials and super funny. Atul and I watched together, and then when I reached a point where I felt like I could try something, I would stop and make something in CodePen. I chose CodePen because it was a great environment for me to prototype an idea and then share it with Atul, so that he could then provide me mentorship directly in the code, or if we weren’t physically next to each other, with Screenhero.

My first little project that I made for myself was designing a lumberjack. I don’t know where the idea came from, but I just went for it. Like most of my projects, I started by sketching in my notebook.

This helped me to think through how I could break down my concept into shapes, which I could then reference in the documentation section on the p5 site.

The first thing that I realized was a challenge for me was understanding the canvas. It’s basically the first thing that you do when you start a sketch in p5, and I get the general size of the container that I’m working in, but when I was making shapes, I was ballparking it - almost as if I had imaginary rulers on the page guiding my designs. Once I got the hang of that, the project became an exercise in deconstructing my composition into shapes and practicing how they work together, in groups, alone, overlapped, with different opacities, etc.

As I worked, Atul encouraged me to keep my thoughts about how to improve the tools in a notebook, so that once I mastered the technical skills, we prototype making the user experience better for learners. My notes are pretty simple, they look like this:

Canvas - why is it stuck to the edge? I want to move it to the center
Is there a chart somewhere that shows all the RGB values?
You can’t copy and paste from the documentation.
You can’t have two functions that are named the same thing. 
You need to specify what functions will be “drawing” by putting them under the draw function and then calling them.
I wish there was a ruler
I wish that there was a color picker in the IDE
I wish that the p5 site was responsive because I make the reference screen small while I’m coding 
Error: Uncaught SyntaxError: missing ) after argument list    <— that feels really wordy and confusing, just tell me I forgot a closing parenthesis.
The comments in the code in the examples aren’t legible if they are long lines on copy.
The edit and reset buttons cover the documentation

Here’s what the Lumberjack looks like right now. You can check it out on my CodePen. It even has a little animation - with a wink that I threw in there!

See the Pen Lumberjack by Jess (@iamjessklein) on CodePen.

At this point all of my notes that I created from this exercise have been converted into github issues in the p5 website repo. So, the question of the day: was I able to feel like I was tinkering with p5? Yes. I think that the reason why was that I was able to start and end small. I wasn’t building an application or website, just a simple illustration. It’s something that I was able to do by myself, but the learning experience was greatly improved by having a more advanced learner such as Atul by my side. The resources on the p5 website are great; I ended up supplementing them a bit with Getting Started with p5.js by Lauren McCarthy, Casey Reas and Ben Fry.

I’m now wondering how I might improve this exact experience for learners. Here are some initial thoughts:

Make documentation forkable/remixable. Using CodePen was invaluable for me. I could code, not have to deal with servers and it felt like a safe space to fail. It also provided a way for me to pass around code with Atul fairly easily. This is currently a bit challenging to do via the p5 reference library. There are some simple solutions such as widgetizing elements that would support this kind of interaction.
Start a community gallery for examples. Getting Started with P5.js had some great examples, and the p5 website itself has even more examples on the homepage - but either the examples are too basic or unfathomable. I want an easy way to see designs and code examples. This will do two things: 1. Expose the design process and thinking behind p5 sketches. 2. Raise the bar of work done in the field, by essentially crafting an online gallery space.
Make errors friendlier. I failed a lot in this experiment, but because of mentorship and the approachability of the p5 suite of tools, I felt compelled to continue on my coding quest. This kind of support can be translated into simple errors and suggestive, didatic resources.

That’s where I’m at now. I am going to work a bit on tackling these ideas with Atul and the p5 team and continue to build out the animations for the lumberjack. I’d love to hear from you. As a learner, have you experimented with peer learning through pair programming or like in my case, peer binge watching YouTube tutorials? What has been an effective learning technique or tool for you?

Feel free to tweet your responses to @iamjessklein!

Overwriting p5 Globals

Tue, 05 Apr 2016 00:00:00 +0000

It turns out that one of the problems with having global functions with very simple names like text is that beginners may accidentally overwrite them, and then become confused when they try using them.

This was first brought to our attention when a newcomer to p5 filed issue #1314.

Ultimately, the problem was fixed by PR #1318, which logs helpful warnings if the user overwrites global functions.

For example, the following sketch:

function setup() {
  text += "blarg";
}

logs this warning:

You just changed the value of "text", which was a p5 function.
This could cause problems later if you're not careful.

Hopefully this change will make it easier for users to debug their sketches.

A Note About Community

One of the particular things I like about this story is the way the p5 community responded to it. While many open-source projects would immediately dismiss an issue like #1314 as “user error” and be done with it, the p5 community instead helped the user debug their problem, and then wondered if there was a way to alleviate such a frustrating experience. Potential solutions were proposed, community members responded with helpful feedback, and the original bug reporter was treated like a valuable contributor (which they were!) rather than being dismissed as a noob.

I wish all open-source communities worked this way.

TypeScript to the Rescue

Wed, 16 Mar 2016 00:00:00 +0000

After writing about Unit Testing Reference Documentation, I realized that there’s a very interesting tool that can help us ensure the quality of our documentation and improve the development experience for p5 beginners and experts alike.

It’s called TypeScript. It basically adds a nice layer of type-checking on top of JavaScript, and the great thing about it is that you don’t even really need to know anything about it in order to benefit from it. For example, it allows us to build helpful autocomplete interfaces like this:

The above animated GIF happens to be taken from a session of Sublime Text with the TypeScript plugin installed, but similar plugins exist for other editors like Atom. With a bit of work, we can build similar functionality into the p5 IDE itself!

Thanks to TypeScript’s static analysis, we can also use it to provide friendly error feedback before the user has even started running their code. For example, here’s what it looks like in Sublime Text when we pass a string instead of a number as the first parameter of createCanvas():

Compared to the standards of the friendly error system, that feedback isn’t particularly amicable, but we can do better if we integrate custom support into the p5 IDE. The important thing here is that we’re able to leverage the rich set of static analysis functionality that TypeScript provides us, all without needing the user to know anything about TypeScript itself.

How It Works

Before reading this section, you’ll probably want to review the Unit Testing Reference Documentation post if you haven’t already.

I wrote a generate-typescript-annotations.js script that essentially converts p5’s YUIDoc metadata into something called a TypeScript declaration file. For example, here’s what the auto-generated entry for createCanvas() looks like:

/**
 * Creates a canvas element in the document, and sets the dimensions of it
 * in pixels.
 */
declare function createCanvas(w: number, h: number, renderer?: string): any;

Actually, the aforementioned script generates two TypeScript declaration files, which correspond to the different ways in which p5 can be used:

p5.d.ts contains TypeScript declarations for p5’s instance mode, which is the way to use p5.js if you want to work with other third-party libraries (or just generally keep your global scope clean).
p5.global-mode.d.ts contains TypeScript declarations for p5’s global mode, which is what beginners use, and what most example code snippets lying around the Web use.

Note that these files aren’t completely accurate yet, as there are some wrinkles involved in converting p5’s YUIDoc metadata into TypeScript declaration files. The methods and properties that haven’t been converted yet are commented-out, with additional comments explaining the problems the conversion script ran into.

While it’s certainly possible to not auto-generate the TypeScript declaration files from p5’s YUIDoc metadata, I think that doing so keeps things nice and DRY. It also serves as a nice “forcing function” to ensure the quality of our documentation!

Ensuring Quality

Aside from making it easier for people to learn p5 and fix their errors before they run their code, we can also use these TypeScript declaration files to ensure that p5’s own example snippets are error-free.

Because TypeScript works via static analysis, we don’t even need to run our example snippets: it should be fairly straightforward to write a test suite that just iterates through all of p5’s reference documentation examples, manual test examples, and examples on p5js.org to ensure that our YUIDoc metadata and our example code agree with one another.

Unit Testing Reference Documentation

Sat, 05 Mar 2016 00:00:00 +0000

Part of the work of the Friendly Error Fellowship involves resurrecting the original work on p5’s Friendly Debugger, which was disabled due to various limitations documented in #971.

One of the core features of the legacy Friendly Debugger was an argument validator, which would:

Check that a function call contains the correct number of parameters, and
Check that a function call contains the correct type of parameters.

This would be useful for beginners in particular. For instance, imagine passing a number into a p5 function that expects a string; if the function’s implementation calls toUpperCase() on the argument, this will result in TypeError: toUpperCase is not a function being raised, which will be quite confusing to newcomers. Much more helpful will be to log a friendly error suggesting the user pass in a string instead.

Now, let’s take a quick detour to look at how p5’s reference documentation is defined. We use a tool called YUIDoc that generates it from some specially-formatted comment blocks in p5’s source code that look like this:

 * @method color
 * @param  {Number|String} v1   gray value or red or hue value relative to
 *                              the current color range, or a color string
 * @param  {Number}        [v2]    gray value or green or saturation value
 *                                 relative to the current color range (or
 *                                 alpha value if first param is gray value)
 * @param  {Number}        [v3]    gray value or blue or brightness value
 *                                 relative to the current color range
 * @param  {Number}        [alpha] alpha value relative to current color range

The above is a snippet taken from the source code for p5.color(), and is used to generate its documentation.

As Jason Sigal brought up in #759, it should theoretically be possible to take the metadata extracted from such comment blocks, and leverage it to do some of our type-checking for us, rather than violating DRY, potentially introducing more errors, and complicating our codebase by manually writing extra type validation code.

However, we’re also in a bit of a bind because we don’t actually know if our reference documentation is correct. It would be really unfortunate for the friendly error system to give the wrong kind of advice to beginners, increasing their frustration even more!

So how might we “unit test” our own reference documentation?

Here’s one approach: write a type-checker that uses p5’s own YUIDoc metadata, and use it to type check p5’s own example snippets.

Doing this has a few advantages:

It ensures that our documentation is accurate. For example, if a working example snippet is passing a p5.Color instance as a first argument to lerpColor() but this isn’t documented as a valid argument type, our type checker will complain. We fix the bug by fixing our documentation.
Conversely, it helps ensure the quality of our example snippets. If our example snippet is calling a p5 API the wrong way, it’s probably broken!
It’s possible that we can reuse the type-checking logic to resurrect the Friendly Debugger’s type-checking system going forward.

I’m now working on one approach to this kind of solution in #1287.

Using p5 Globals in Top-Level Code

Mon, 22 Feb 2016 00:00:00 +0000

One of the unintuitive aspects of p5 that beginners often make is using p5 globals in their “top level” code, i.e. outside of setup() and draw():

var myColor = color('blue');

function setup() {
  background(myColor);
}

Believe it or not, this sketch doesn’t work, and will result in the following error being thrown:

ReferenceError: color is not defined

The full reasoning and workaround for this is described in the p5 FAQ, suffice to say that programmers of all experience levels encounter it a lot.

It’s hard to detect such errors with 100% accuracy, but in #1130 I added some code that attempts to detect it, and in #1256 I improved on it so that the following console message is now displayed when the above sketch runs:

Did you just try to use p5.js's color() function? If so, you may want to move it into your sketch's setup() function.

For more details, see: https://github.com/processing/p5.js/wiki/Frequently-Asked-Questions#why-cant-i-assign-variables-using-p5-functions-and-variables-before-setup

I wish there was an easy way to get feedback on whether users actually find this message helpful. I can think of a few solutions to this, but more on that in a future blog post!

Towards Zero Errors

Fri, 12 Feb 2016 00:00:00 +0000

What’s better than friendly errors? Zero errors! We can help ensure this if we have accurate documentation.

But one of the hardest things about fixing a mistake in the documentation is figuring out where it’s located in a project’s source code.

So I thought that it might be nice to unintrusively link to the source code for a p5 API in its documentation. I stress the word unintrusively because I don’t want to confuse the beginners who may be learning programming for the first time, and could be thrown off by the extra information.

Other benefits of linking to the source:

It invites users of p5 to become contributors.
It generally makes it easier to “pop open the hood” and see how p5 works.

Here’s what it looks like–the example screenshot below is taken from the documentation for plane():

The first link there is to view the source for plane(), while the second is to edit it (yay to GitHub for providing permalinks to edit files at a specific line number!). My hope is that beginners who don’t know anything about git can fix simple typos and issue PRs for them.

This was filed as pull request #1248.