DEV Community

Autumn
Autumn

Posted on

How do you design good error messages?

Hi! I'm building a framework in Python for 10 - 11 year olds to learn Reninforcement Learning. What are your best tips / tricks for designing good & effective error messages?

Top comments (3)

Collapse
 
hamatti profile image
Juha-Matti Santala • Edited

First, couple of general ideas for error messages and I'll talk about programming library ones in the end.

Sonya Gregory has really good points about errors in regards to user experience in her blog post Best Error Messages: 5 Tips For A User-Friendly Experience.

My takeaways from her post:

  1. Is it because of something that user did wrong? Be as specific as possible.
  2. Be human. People don't generally want to talk to a computer so make your error messages feel like they are humane.
  3. Humor can make a frustrating situation less threatening but needs to be used carefully.
  4. Help your user to figure out what's wrong.

In addition to those, I think that Daniel's comment is very on point. Having error codes that match to very specific cases can help people who've built the original program to pin point the issues. You can even add "Please let us know what you were doing when this happened" flavor text (with bit more specificity) to help you get the information that you need to figure the problem out.

When it comes to libraries used to build programs, they can be very awful. As much as I love Python, its error messages are so bad I'm writing a guide to understand them. On the other hand, Elm has brilliant approach to it and I recommend reading through the linked post.

Making your error codes as good and helpful as those of Elm's is a lot of work but it can make a huge difference, especially in this case since you're building things for children.

Carlos' point is also good and I'd expand to that. With a small library, you might not get a lot of hits on Google with the error codes so make your documentation so that it's easy to search with an error code. That will save your users a lot of trouble.

Collapse
 
autiomaa profile image
Daniel Schildt

Have both description text and error code, because there could be duplicated texts. Avoid making duplicated error codes.

Collapse
 
carloswosiak profile image
Carlos Wosiak

Those which you copy/paste on google and find how to solve it.