Improving Processing Error Messages

Created by: WillRabalais04

Processing Friendly Errors

We are building out friendly error message rewriting by extending the PreprocessIssueMessageSimplifier. To determine which errors to support, we worked with Raphaël and Sam to run a community survey.

Motivations

The results of the survey showed that although the error messages are usable, with an average clarity rating of 3.32 out of 5 there is room for improvement. The key elements that respondents identified as crucial for understanding error messages include the name and type of the error, specifics about what broke in the code, traceback to the specific line of the error, expected versus found outcomes, resources for contextualization and guidance, and possible solutions. Enhancing error messages based on the insights of the survey would greatly benefit the Processing user experience for beginners and advanced users alike. We hope to foster better understanding and more efficient problem-solving.

Currently Simplified Errors to Improve On

Errors to Add Strategies For

Unsupported Errors

The following will still operate as usual without rewriting / error simplification.

• Variable is named after keyword
• GLSL/Shader errors
• Compatibility issues with Android extensions
• Library errors
• Python errors
• p5.js errors

Error Message Template

* The toggle to see the original error will be added at some point but likely will not be in the first version of the improved error messages as it may be difficult to implement.

Example 1: Array Index Out of Bound Exception

🔵 Processing says: Oops! It looks like you're trying to look at an item in your 'numbers' array that doesn't exist. (On line 3 in sketch_230707c.pde)

Remember, counting in Processing starts from 0, not 1. This means your 'numbers' array, which has 3 items, has positions labelled from 0 to 2. If you're trying to find an item at position 3 and above (or below 0), it won't work because there's no item there!
To fix this, make sure you're looking at positions that exist in your 'numbers' array, that is, positions from 0 to 2.

For more:https://processing.org/examples/array.html

Example 2: Invalid Identifier

🔵 Processing says: Uh-oh! There's an issue with a "bad identifier" in your code. Specifically, the issue is with 'int 9'. (On line 48 in sketch_230710a.pde)

In Processing, identifiers (like variable names, function names, etc.) can not start with a number and should only include letters, numbers, or underscores. Therefore, '9' is not a valid name.

Here's a quick fix: Try renaming your identifier so that it starts with a letter, dollar sign($) or an underscore(_). Make sure the name you choose is not a reserved keyword like "setup" or "width".

For more:
https://processing.org/examples/variables.html
https://processing.org/examples/functions.html

Incorporating Additional Resources Approach

• When directing the users to external resources the goal is to direct them towards Processing resources when possible and towards official Java documentation as a last resort as it is significantly less user friendly than Processing resources.
• To not overwhelm the user with links to external resources we will link them inline with the error message if the keyword is conveniently in the message itself otherwise they will be in the "For more:" section at the bottom. The "For more:" section will also contain examples of the concepts when applicable.

从 java/src/processing/mode/java/preproc/PreprocessIssueMessageSimplifier.java 开始，根据调查结果、优先级列表和提议的错误消息模板，审查现有策略。该 issue 涉及许多异常类型以及多项消息设计决策；要完成这项工作，需要确定一致认可的范围，并实现选定的友好化重写，包括相关资源和上下文指导。