More helpful exceptions/warnings

[Christopher Pitt]

Hey folks,

I've been thinking about making exceptions/warnings more useful, during development. I've put my thoughts into a couple pull request:

https://github.com/silverstripe/silverstripe-framework/pull/5953

https://github.com/silverstripe/silverstripe-framework/pull/5963

I'm trying to explain the problem in more detail, and offer guidance on the correct approach to overcoming common problems. There's been a lot of great discussion there (especially on the first PR), and there have also been some good questions:

1. "Why don't we just link to documentation?" — Damian and Chris J
   
2. "What about using templates?" — Chris J
   
3. "What about translations for these messages (and the missing multi-line translation support required for it)?" — Sam, Chris J
   
4. "Is this new functionality (minor version bump)?" — Dan

I have offered the following reasons:

1. Sometimes there just isn't documentation. We could (and should) improve that, but I still think there's value in a gentle nudge in the right direction; at the point of exception/warning.
   
2. I think it would be best to avoid as much framework code as possible, since anything could be generating the exceptions/warnings. A compromise of this would be a limited set of small, well-isolated helper functions; for loading and formatting the messages.
   
3. Translations would be fantastic. I'm not sure where the appropriate place to select a locale would be, but English is a sensible default. The translation code needs work for this to happen. Writing the messages is a good first-step (because they can be ported to language files easily enough).
   
4. I don't believe this is new functionality, and I do believe it will be helpful to developers right now. 4.0 could take a little while, and developers could be stuck on ^3.4 for a long time still. Special care needs to be given so that this "clean-up"/"improvement" does not introduce new features beyond the goal of more helpful exceptions/warnings.

I was wondering if others had interesting perspectives on the suggested improvements to exceptions/warnings, or other questions we hadn't yet considered...

Kind regards

Chris

[Sam Minnée]

In general, I think that a self-documenting exception messages are a great idea.

Oh point #4 I think that merging to the 3 branch (for a 3.5 release) would be the best bet. If it's literally just a longer exception message, 3.4 would be okay, but if we end up looking into points #2 or #3 we'd likely get some new features. I don't think it needs to be embargoed until 4.0.

On point #3, we'd want to see if transifex can support multi-line strings.

Other other point I think we need to consider is how this will affect various consumers of exception messages. Some key ones for me are:

 - CLI dump

 - HTML dump in a web view

 - syslog

 - log to a text file

 - log to graylog

We could either log the entire multiline view, or for logs where that's more intrusive, we should ensure that cropping all but the first line provides a shorter summary of the problem (this is a common practise in git summaries too)

The only other thing I wonder is whether we should be using a subclass of Exception, with separate message and description parameters. That way, we could handle the description property only in cases where it's of use.

I'm not convinced that pouring this volume of information into a typical error log is the best idea. However, for something like Raygun, it would be great, because it has better support for digging into the details of a single error. The silverstripe-raygun module could be extended to handle DetailedException.

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at https://groups.google.com/group/silverstripe-dev.
For more options, visit https://groups.google.com/d/optout.

--

Sam Minnée

CEO

SilverStripe Limited

[Daniel Hensby]

I'm a fan of this idea. Though a few thoughts:

1. I don't think translations of error exceptions are needed if exceptions are aimed at the developer rather than the end user (pretty sure they are as we don't have an elegant way of showing exception messages to users?!)
2. I'd like to explore some kind of standard way to define these callbacks globally or at least in a kind of "autoloady" way rather than including a file in a relative path as has been demonstrated in the PR(s)
3. Exceptions are a great place to explain why something has happened and possible causes - docs aren't always the best place for this and can be hard to find or know where to look. I have found more and more that most of the effort of debugging is understanding the error message, so if we can lower the barrier to understand the message, then that's a big positive.

[Ingo Schommer]

Thanks for caring about this, Chris - SilverStripe exceptions don't, uhm always aid troubleshooing. I like the longer exception format!

Are you suggesting that we follow the external messages/MyMessage.php format for all exceptions?

I think that most exceptions will be single-use in a quite specific context, and could easily be handled via sprintf() inline.

Many of the core exceptions could be more verbose, I don't have a problem with longer PHP methods because of a few lines of exception strings though.

Translation of messages isn't a high priority here IMHO - developers working with SilverStripe already need to have a good enough grasp of the English language to work with the SilverStripe core PHP API itself, as well as the untranslated PHPDoc. Given the complexities of having translation code take part in exceptions (what if the translation code itself causes/swallows exceptions), I'd rather stick to the default language. If it really becomes an issue, we can always go the React route and link to (translated) website content in our error messages.

To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-dev+unsubscribe@googlegroups.com.
To post to this group, send email to silverstripe-dev@googlegroups.com.

Visit this group at https://groups.google.com/group/silverstripe-dev.
For more options, visit https://groups.google.com/d/optout.

--

Ingo Schommer | Solutions Architect
SilverStripe (http://silverstripe.com)
DDI: 04978 7330 ext 4422

Mobile: 0221601782
Skype: chillu23

[Christopher Pitt]

Thanks for the feedback chaps. I'll have a good think about each of your ideas and refactor the pull requests to suite. Once I've done that, I'll come back here for further approval. :)