Example 1: Calculating Percentage

Looking at the error message below, can we pinpoint exactly what went wrong?

Traceback (most recent call last):
  File "main.py", line 42, in 
    percentage(numerator, denominator)
Exception: Something went wrong.

This error message doesn’t provide any information about the error that occurred. The only useful information is from the stack trace pointing to the percentage() function.

We can improve this by providing enough information to diagnose the issue through specific error types along with debugging suggestions.

Traceback (most recent call last):
  File "main.py", line 42, in 
    percentage(numerator, denominator)
ZeroDivisionError: Division by zero when calculating percentage. Check if the denominator 0.

This error message helps determine the root cause of the error and provides possible steps to resolve it. It also uses consistent language when referring to the function parameters for clarity to avoid confusion.


Example 2: Parsing Files

This error message is decent and contains information on the type of error that occurs. We know that the file contents may be malformed and our parse() function is unable to successfully interpret the contents.

Traceback (most recent call last):
  File "main.py", line 17, in 
    parse(file_path)
SyntaxError: Failed to parse file.

However, what can we do with this information? This error message is only useful for identifying the error type but is not helpful in determining the root case and finding a solution.

To improve this, we can include code pointers to indicate where it failed and a link to detailed logs as additional resources for further insight into the parsing process. Finally, the error can include information about limitations that are present in the system and are important to be aware of.

Traceback (most recent call last):
  File "main.py", line 17, in 
    parse(file_path)
SyntaxError: Failed to parse file (max size 2MB) at line 42 column 3. Click here to view detailed logs.

Overall, error messages are meant to aid understanding of the problem and help arrive at a solution. They should be clear and concise and simple yet comprehensive.

TLDR

Considerations when writing good error messages:

  1. Use clear and concise error messages to present information to help diagnose the error.
  2. Include helpful pointers and suggestions that provide context to the problem space.
  3. Prioritize clarity and keep language consistent to avoid confusion.

📚 Additional Resources

Here are some additional resources to help understand how error messages and debugging work together: