How to best format exceptions

I’m in the process of working on a library, where I want to have quite expressive exceptions (due to a lot of domain specific constraints). I’m wondering if there any guidelines of how to best format those though?

There are questions like:

  • Are multi line exceptions generally fine?

  • When to start using blame if the stacktrace or expensive operations are not needed?

  • Is it generally ok to add ANSI escape sequences for formatting, or would this cause issues?

I noticed that e.g. the FunctionClauseError exception doesn’t add ANSI sequences by itself, but it’s special cased within IEx to add some proper coloring, while for other exceptions there’s a check for a reset sequence in the exception string.

What do you mean by expressive exceptions? Is there any required format, or in general, a bucket list of requirements?

To me multi-line exceptions are always fine; you either need a stack trace or sometimes the error message cannot be super short. Both things shouldn’t ever be a deal-breaker when constructing exceptions / errors.

Another example: when showing errors in tests I love the “expected X, got Y” format.

I am definitely not an authority on anything (it’s questionable if I’ll be working commercial programming 10 years from now even) but I have found the following format successful when I was working on and with huge Java monstrosities a lifetime ago:

Action: Saving config to ~/.config/my_program/my_program.toml
Error: Access denied
Suggestion: Change the permission flags of the file.

Not specifically, but I was experimenting with e.g. visualizing how a given input string doesn’t fit the things like expected lengths over just showing some abstract numbers.