Ccna final exam - java, php, javascript, ios, cshap all in one. This is a collaboratively edited question and answer site for professional and enthusiast programmers. It's 100% free, no registration required.
Friday, January 13, 2012
@throws tag with exception's parent class name
Sometimes it is impossible to know really thrown exception class name in advance, only in run-time (at least in php). So is it correct to put in @throws tag the parent class of really thrown exception?
If it's "impossible" for you to determine ahead of time what exceptions might be thrown you should consider refactoring. Methods and functions should deal with discrete blocks of functionality that perform specific, testable actions.
Tag your methods with @throws when you've specifically designed them to throw an exception or they invoke other methods that are capable of throwing exceptions. Anything else is an extraordinary condition that shouldn't be documented ahead of time. Although your exceptions will extend the base Exception class, it does you no good to add @throws Exception to every function or method in your code.
So an example: say you're using a custom error handler (using set_error_handlerdocs) to throw an ErrorExceptiondocs on the occurrence of any PHP error. You know the getMyInclude function below is capable of throwing an exception because include will raise an E_WARNING if $file can't be included, so you document that. The getIt function, however, is not capable of throwing an exception so you don't use a @throws line:
<?php
/** * Includes user specified files * * @throws ErrorException On failure to include file */ function getMyInclude($file) { // include include $file; }
/** * Returns the specified argument */ function getIt($x) { return $x; }
?>
Obviously you wouldn't have real-world code like getIt in the above snippet, but you also know it can't throw an exception.
I assume you're talking about docblocks.
ReplyDeleteIf it's "impossible" for you to determine ahead of time what exceptions might be thrown you should consider refactoring. Methods and functions should deal with discrete blocks of functionality that perform specific, testable actions.
Tag your methods with @throws when you've specifically designed them to throw an exception or they invoke other methods that are capable of throwing exceptions. Anything else is an extraordinary condition that shouldn't be documented ahead of time. Although your exceptions will extend the base Exception class, it does you no good to add @throws Exception to every function or method in your code.
So an example: say you're using a custom error handler (using set_error_handlerdocs) to throw an ErrorExceptiondocs on the occurrence of any PHP error. You know the getMyInclude function below is capable of throwing an exception because include will raise an E_WARNING if $file can't be included, so you document that. The getIt function, however, is not capable of throwing an exception so you don't use a @throws line:
<?php
/**
* Includes user specified files
*
* @throws ErrorException On failure to include file
*/
function getMyInclude($file)
{
// include
include $file;
}
/**
* Returns the specified argument
*/
function getIt($x)
{
return $x;
}
?>
Obviously you wouldn't have real-world code like getIt in the above snippet, but you also know it can't throw an exception.