Document standards for exceptions

[aidan-casey]

We have a few standards going on for exception messages. It would be good to document and enforce our standards.

My rough initial proposal would be:

1. Take inspiration from Microsoft
2. Write grammatically correct sentences with punctuation.
3. Include helpful feedback for what might be wrong.

If we can figure out using CI for this too.......... that'd be amazing. 😍

[brendt]

Agree! We also need to replace all default exceptions to custom ones with proper messages.

[innocenzi]

@brendt I think we should do this before 1.0 and rename all exceptions to either be suffixed with Exception or not, currently we do both in different places

[brendt]

So:

• Agree on using proper punctuation and better sentences
• IDK how I feel about ALWAYS using Exception as a suffix or NEVER using it. IMO, it makes sense in some cases but not always

[brendt]

Standards we settled on (still need to document):

• Exception classes should be thought of as events: start with the subject, then the verb in the past tense. <something> <happened>: DatabaseOperationFailed, StorageUsageWasForbidden, AuthenticatedUserWasMissing, etc.
• Never suffix with Exception as it's always clear from the context that this is an exception (either with throw or catch)
• Always extend \Exception
• Preferably, provide an interface that specific exceptions can extend from. Eg. CacheException, DatabaseException, FilesystemException. These interfaces must be suffixed with Exception
• Preferably, overwrite the constructor and only accept the input that's relevant
• Write the exception message in the exception class, not from the context where it was thrown

[brendt]

Ok so with #1308 merged, we need to review the docs:

• [x] Update the docs with new exception names (I reckon a search for "catch", and "Exception" will probably highlight most classes
• [x] Document the new standards (see https://github.com/tempestphp/tempest-framework/issues/499)

@innocenzi will look at it later today

[innocenzi]

We only miss updating exception messages, which can be done over time.

https://tempestphp.com/main/features/exception-handling#customizing-the-error-page https://tempestphp.com/main/extra-topics/contributing#exception-classes