Forum: Ruby rdoc, api + exceptions

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Jon B. (Guest)
on 2006-01-19 19:06
(Received via mailing list)
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
Jim W. (Guest)
on 2006-01-19 22:13
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 W.
Jon B. (Guest)
on 2006-01-19 22:55
(Received via mailing list)
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
This topic is locked and can not be replied to.