[dev] Code/Logic Exceptions vs. Execution Exceptions

[Michael M Slusarz]

Quoting Jan Schneider <jan at horde.org>:

> Zitat von Michael J Rubinsky <mrubinsk at horde.org>:
>
>> Quoting Michael M Slusarz <slusarz at horde.org>:
>>
>>> Before I throw this into CODING_STANDARDS, wanted to run this by the list.
>>>
>>>
>>> Exceptions in Framework Packages
>>> ================================
>>>
>>> Exceptions thrown in packages can be divided into two categories:  
>>> code/logic exceptions and execution exceptions.
>>>
>>> Code/Logic Exceptions
>>> ---------------------
>>>
>>> These are exceptions that should be thrown when there is an issue  
>>> with the programming logic - e.g. the environment was not properly  
>>> set up by an application, or a required parameter was not provided.
>>>
>>> These type of exceptions should throw one of the SPL Exceptions  
>>> (e.g. BadFunctionCallException, LogicException, RuntimeException),  
>>> NOT a package exception.  This ensures that errors will normally  
>>> cause a fatal error, rather than potentially being caught and  
>>> ignored by the calling code.  As such, there is no need to  
>>> document the exception in phpdoc.  Further, the exception messages  
>>> should not be translated, as these messages are intended for  
>>> developers not users.
>>
>> Agreed.
>>
>>> Execution Exceptions
>>> --------------------
>>>
>>> These are exceptions that are thrown due to an error encountered  
>>> while performing the action requested by the calling code.
>>>
>>> Any package that throws at least one execution Exception should  
>>> define a Package_Name_Exception class that extends  
>>> Horde_Exception.  Execution Exceptions should use this class when  
>>> throwing an error.  Any method that throws this kind of exception  
>>> should document it in the phpdoc using the @throws keyword.  These  
>>> messages should be translated, as they potentially could be  
>>> displayed to the user at the application level.
>>
>> Agreed, though I thought at one point we agreed that exceptions  
>> that would be expected to only make it to a log would not be  
>> translated.
>
> Yes, it's a thin line though, because you never know what the  
> exception consumer is doing with it. When we know, this distinction  
> should be done.
>
>> Either way, fine with me as long as it's standardized.
>
> Overall +1

Added to CODING_STANDARDS.  Further tweaks can be done directly to the file.

michael

___________________________________
Michael Slusarz [slusarz at horde.org]