P5.js: FES: Friendly messages for global errors

[akshay-99]

Most appropriate sub-area of p5.js?

• [x] Other (Friendly Errors)

There are a lot of errors that a person may encounter when writing a sketch. Some of these are quite straight forward, while others are more cryptic. It would be nice if the FES can monitor all the errors that arise, and see if it can give a simplified explanation for them and so I browsed through the discourse forum to learn about the errors that usually confuse people.

It may be useful to differentiate between errors that happen in the user's sketch and those that happen within the p5 library. I had first thought about this when I read this comment. The code inside the library is not within the user's control and so it's not helpful if the focus is put on a line inside the library. A friendlier error message would instead focus on the sketch line that called the library function, and inform the user that it either probably has something to do with the arguments they passed (so they should check the reference once), or they may have stumbled upon some unexpected behaviour of the library ( so they should ask someone, maybe on the forum or here on Github ). Below is another example error message I came across while browsing through discourse forum here

Uncaught (in promise) Error: [object Arguments]is not a valid color representation.
    at _main.default.Color._parseInputs (p5.js:43255)
    at new _main.default.Color (p5.js:42293)
    at p5._main.default.color (p5.js:41912)
    at _main.default.Renderer2D.stroke (p5.js:50518)
    at p5._main.default.stroke (p5.js:44066) // The first useful line in the message
    at setup (sketch.js:4) 
    at _setup (p5.js:48328)
    at _runIfPreloadsAreDone (p5.js:48266)
    at p5._decrementPreload (p5.js:48275)
    at p5.<anonymous> (p5.sound.min.js:2)

Although many of the argument scenarios can be dealt with by expanding the use of validateParameters for more functions, it would impact performance. Some of these errors can arise even if the argument type is correct (as seen in the comment mentioned above). Also for most errors, much of the stacktrace is not that useful without deep knowledge. It is possible to simplify things by removing details about internal library calls. This can be even applied to errors that happen outside the library.

The FES can even provide help with errors not related to p5 functionality. Common errors I found on the forum were due to mistakes in understanding variable scope. These result in ReferenceError and TypeError. It is possible to add more explanation to them, while also giving some debugging tips along the way, such as taking a look at where the variable is defined, proving a few links etc. MDN has a nice list of various errors across browsers which we can use to determine the kind of error and show the appropriate help message.

I would greatly appreciate more ideas in addressing difficulties that people usually face when understanding errors.

Suggestions for global errors that FES could catch and reword:

• Simplify stack trace, hide internal details
• ReferenceError and TypeError

[stalgiag]

@akshay-99 thanks for doing more research and coming up with these ideas. I hope you don't mind but I took the liberty of editing your post so that there is a list of ideas at the bottom. Can you keep this list updated as ideas are suggested or ruled out?

I am going to brazenly tag people that might have insight into cryptic errors that new coders encounter often. @kjhollen @lmccart @GoToLoop @shiffman @brysonian -- Any wishlist items for errors that the friendly error system could reword?

[akshay-99]

Hi @stalgiag, the error message starting with Error: [object Arguments]is not a valid color representation was just meant as an example to support the argument for simplifying the stack trace, so I am changing that point to just "simplify stack trace and remove internal details" :smile: And yes I would be happy to maintain this list of ideas.

[lmccart]

@akshay-99 excited about this work!

If I'm understanding correctly, we're looking for common errors that are JS level, rather than p5 specific, correct? I think the two you've identified already are very common ones. To be more specific on a few frequently occurring ones:

• Uncaught TypeError: Cannot read property 'blah' of undefined
• SyntaxError: Unexpected token - usually a typo, but hard for students to understand this language
• SyntaxError: Illegal Character - commonly happens when copy and pasting from other documents
• ReferenceError: "x" is not defined - common scope error

[akshay-99]

Thanks @lmccart !

If I'm understanding correctly, we're looking for common errors that are JS level, rather than p5 specific, correct?

Yes!

SyntaxError: Unexpected token - usually a typo, but hard for students to understand this language
SyntaxError: Illegal Character - commonly happens when copy and pasting from other documents

I was thinking about Syntax Errors but I wasn't sure if handling them would be possible as they occur during parsing, as opposed to those which happen during execution. I will see what can be done.

[brysonian]

I don't have much to add, other than maybe there should be some thought into what goes into the library, and what goes into the editor via linting. Of course new coders aren't always using the p5 editor, so there is a judgement as to who is being supported. But i guess my worry is that adding too much to the lib itself will impact performance, and that many of these errors are better caught via linting.

[akshay-99]

Thanks @brysonian! I understand these concerns. It is true that some of these issues can be addressed by linting. But the FES approach used here is different in the sense that it only reacts to actual errors. This is also why I think that the performance impact would be felt only when there is an actual error, which is a reasonable pay-off I think (in most cases if there is an error, the sketch cannot continue running anyway). Another thing was that I think linting can often impose a certain style, and sometimes raise a bunch of false positives ( which for experienced programmers is often only a minor annoyance but can be very troubling for beginners ).

The added complexity is a concern I have too when implementing these changes, in the sense that it adds a lot more extra weight to FES and the library. I try to keep it as small as I can.