rdoc, api + exceptions

Discussion in 'Ruby' started by Jon Baer, Jan 19, 2006.

  1. Jon Baer

    Jon Baer Guest

    Hi,

    Ive become a pretty big fan of Ruby in the past month during my time
    off and while going through PickAxe book and looking around Im not
    sure if im missing something fundamental about exceptions ... (bare
    w/ me as I am a Java/PHP convert)

    Normally when developing an API you can express what exceptions may
    occur when invoking a particular method ...

    public foobar() throws BadFooBarException

    In Ruby, it would seem to me that nearly ~everything~ can throw at
    least one exception (or at least cause NameError), so Im wondering at
    least how you would document that your method should be placed in a
    begin/rescue/end block from a custom exception.

    Thanks!

    - Jon
     
    Jon Baer, Jan 19, 2006
    #1
    1. Advertising

  2. Jon Baer

    Jim Weirich Guest

    jon baer wrote:
    > Normally when developing an API you can express what exceptions may
    > occur when invoking a particular method ...
    >
    > public foobar() throws BadFooBarException
    >
    > In Ruby, it would seem to me that nearly ~everything~ can throw at
    > least one exception (or at least cause NameError), so Im wondering at
    > least how you would document that your method should be placed in a
    > begin/rescue/end block from a custom exception.


    I follow a simple rule when dealing with exceptions and it works equally
    well in Java or Ruby.

    Every method has a purpose. If a method is unable to achieve its
    purpose, then it must fail (and indicate failure via an exception).

    So when do you wrap a method in a begin/rescue clause? When the failure
    of a called method should not cause the failure of the calling method.
    Rescue the failure, attempt to fix it and continue.

    When you think of the problem in terms of success/failure, then the type
    of failure is usually not important. This means you don't (usually)
    have to worry about exactly which type of exception is being thrown and
    making sure you capture each and every possible exception type (which
    creates quite fragile programs IMHO).

    --
    -- Jim Weirich

    --
    Posted via http://www.ruby-forum.com/.
     
    Jim Weirich, Jan 19, 2006
    #2
    1. Advertising

  3. Jon Baer

    Jon Baer Guest

    I guess this stems from not having to "precompile" an app vs. only
    having the exception come up at runtime.

    For example when using ActiveRecord for the first time I was unaware
    that a specific type of exception could occur based on a record not
    being located (which is obvious) but what type of exception I was
    expected to trap was not + only found during unit/web test.

    <op>
    It would be nice to have something equivalent to @throws in rdoc to
    highlight what might occur.
    </op>

    - Jon

    On Jan 19, 2006, at 2:36 PM, Jim Weirich wrote:

    > jon baer wrote:
    >> Normally when developing an API you can express what exceptions may
    >> occur when invoking a particular method ...
    >>
    >> public foobar() throws BadFooBarException
    >>
    >> In Ruby, it would seem to me that nearly ~everything~ can throw at
    >> least one exception (or at least cause NameError), so Im wondering at
    >> least how you would document that your method should be placed in a
    >> begin/rescue/end block from a custom exception.

    >
    > I follow a simple rule when dealing with exceptions and it works
    > equally
    > well in Java or Ruby.
    >
    > Every method has a purpose. If a method is unable to achieve its
    > purpose, then it must fail (and indicate failure via an exception).
    >
    > So when do you wrap a method in a begin/rescue clause? When the
    > failure
    > of a called method should not cause the failure of the calling method.
    > Rescue the failure, attempt to fix it and continue.
    >
    > When you think of the problem in terms of success/failure, then the
    > type
    > of failure is usually not important. This means you don't (usually)
    > have to worry about exactly which type of exception is being thrown
    > and
    > making sure you capture each and every possible exception type (which
    > creates quite fragile programs IMHO).
    >
    > --
    > -- Jim Weirich
    >
    > --
    > Posted via http://www.ruby-forum.com/.
    >
    >
     
    Jon Baer, Jan 19, 2006
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Andreas Schwarz
    Replies:
    6
    Views:
    283
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    164
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    157
    Dave Thomas
    Nov 2, 2004
  4. Iwan van der Kleyn

    rdoc: how to add readme.rdoc as index.html?

    Iwan van der Kleyn, Apr 26, 2005, in forum: Ruby
    Replies:
    1
    Views:
    264
    Stefan Lang
    Apr 26, 2005
  5. Paul Van Delst

    How to use rdoc parsers outside of rdoc?

    Paul Van Delst, Jul 27, 2006, in forum: Ruby
    Replies:
    0
    Views:
    121
    Paul Van Delst
    Jul 27, 2006
Loading...

Share This Page