Skip to main content

@throws tag with exception's parent class name

Image
By User



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?




Labels:

Comments

  1. AdminJanuary 14, 2012 at 4:35 AM

    I assume you're talking about docblocks.

    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.

    ReplyDelete

Post a Comment

Popular posts from this blog

Why is this Javascript much *slower* than its jQuery equivalent?

By User
I have a HTML list of about 500 items and a "filter" box above it. I started by using jQuery to filter the list when I typed a letter (timing code added later): $('#filter').keyup( function() { var jqStart = (new Date).getTime(); var search = $(this).val().toLowerCase(); var $list = $('ul.ablist > li'); $list.each( function() { if ( $(this).text().toLowerCase().indexOf(search) === -1 ) $(this).hide(); else $(this).show(); } ); console.log('Time: ' + ((new Date).getTime() - jqStart)); } ); However, there was a couple of seconds delay after typing each letter (particularly the first letter). So I thought it may be slightly quicker if I used plain Javascript (I read recently that jQuery's each function is particularly slow). Here's my JS equivalent: document.getElementById('filter').addEventListener( 'keyup', function () { var jsStart = (new Date).getTime()...
3 comments
Read more

Is it possible to have IF statement in an Echo statement in PHP

By User
Thanks in advance. I did look at the other questions/answers that were similar and didn't find exactly what I was looking for. I'm trying to do this, am I on the right path? echo " <div id='tabs-".$match."'> <textarea id='".$match."' name='".$match."'>". if ($COLUMN_NAME === $match) { echo $FIELD_WITH_COLUMN_NAME; } else { } ."</textarea> <script type='text/javascript'> CKEDITOR.replace( '".$match."' ); </script> </div>"; I am getting the following error message in the browser: Parse error: syntax error, unexpected T_IF Please let me know if this is the right way to go about nesting an IF statement inside an echo. Thank you.
5 comments
Read more