benfry
Friendly error messages with expanded content
Superceeds https://github.com/processing/processing4/pull/747, https://github.com/processing/processing4/pull/748, and https://github.com/processing/processing4/pull/749. This is for Google Summer of Code project on friendly error messages (see https://github.com/processing/processing4/issues/741). This is led by @WillRabalais04.
Hey @WillRabalais04! You are doing a great job. I will leave some comments here for you to address before the end of GSoC. Thanks!
Hey @WillRabalais04! This is great thanks. I can't believe today is your last day for GSoC! We really appreciate everything you did for us this summer. I know we still need to tackle message localization and potentially some related copy edits on our side before this can go in (that are outside the scope of your GSoC work) so I will leave this as draft until @SableRaf and I connect on that final piece. This is a fantastic contribution! Please let me know if there is anything else I can do as you finish up.
Final Report GSoC'23
Project: Improving Friendly Error Messages
Student: Will Rabalais
Mentors: Sam Pottinger & Raphaël de Courville
Organization: Processing
Project Overview
The Friendly Error Messages for Processing project aimed to improve the way error messages are displayed to users, enhancing the debugging experience by providing concise yet informative error messages with context, external resources and line numbers when possible. The project is an addition to the existing Processing error message system, adding more extensive error messages so that it resembles the P5.js Friendly Error System (FES). The challenge was that error messages generated by the compiler and the Java Virtual Machine are often vague, full of jargon and inaccessible to new programmers. The primary objective was to explain the error while and presenting the underlying cause in a manner more beginner friendly. Moreover, these revamped error messages featured direct links to relevant documentation for a deeper understanding of the issues.
Features Added
- Simplified Error Messages: The existing error messages were often cryptic and challenging to understand for new developers. This project simplified the error messages by breaking them down into digestible components while retaining the necessary technical information. These error messages are accessible when an error is triggered via a new button (ℹ️) as seen below.
- Contextual Information: Alongside the error message itself, the enhanced popup displayed additional contextual information, such as the relevant code snippet, variable values, or function call stack. This contextual data aimed to provide developers with a clearer understanding of the error's origin.
- Improvements to the debugger: https://github.com/processing/processing4/pull/729 (and https://github.com/processing/processing4/pull/692)
- External Links: The enhanced error message included external links to relevant Processing Reference documentation, tutorials, or community discussions, assisting developers in troubleshooting and resolving issues efficiently.
Libraries Used
- Flexmark Library: Flexmark is a Java library used for parsing and rendering Markdown content. In this project, Flexmark was employed to convert markdown-formatted error descriptions into HTML for rendering within the popup.
- StringTemplate Library: StringTemplate is a template engine that allows for dynamic generation of textual output. It was used to create error message templates capable of incorporating specific statements from the code that likely caused the error and line numbers.
- Ant: Indirectly used, part of Processing's build system.
- Swing: Used to extend the Processing Development Environment.
Screenshots
What’s Left to Improve
- Originally we had aimed to include features such as a translation engine that for the friendly errors and an error log however due to time constraints these were not implemented.
- Expand test coverage
- Verify language server support
What I Personally Learned
The biggest challenge for me was experiencing a large codebase for the first time. I found that it required a different mindset than a smaller project does. I was also exposed to new libraries, design patterns and development practices. Working collaboratively with tools such as Git was also relatively new to me and I believe that learning in collaborative environment in which people depended on me I learned quicker than I would have on my own.
Thanks @WillRabalais04! We can work with our various volunteer localizers to take care of localization and the language server after localization!
I also added your debugger fix to your final report! That's happily already in production shipped to thousands of developers <3
Hey @WillRabalais04! This is great thanks. I can't believe today is your last day for GSoC! We really appreciate everything you did for us this summer. I know we still need to tackle message localization and potentially some related copy edits on our side before this can go in (that are outside the scope of your GSoC work) so I will leave this as draft until @SableRaf and I connect on that final piece. This is a fantastic contribution! Please let me know if there is anything else I can do as you finish up.
It was great working with you and @SableRaf! It's great to know that this is going to be maintained after the GSoC period is over and I'm happy to keep contributing.
I also added your debugger fix to your final report! That's happily already in production shipped to thousands of developers <3
Awesome!
