From: Tim Pease <tim.pease@...>
Date: 2006-06-29T05:08:22+09:00
Subject: Re: General API design question: FooError vs Foo::Error

On 6/28/06, Berger, Daniel <Daniel.Berger@qwest.com> wrote:
> > -----Original Message-----
> > From: Daniel Berger [mailto:djberg96@gmail.com]
> > Sent: Sunday, June 18, 2006 1:44 PM
> > To: ruby-talk ML
> > Subject: General API design question: FooError vs Foo::Error
> >
> >
> > Hi all,
> >
> > I've noticed that some libs have changed from a class like
> > FooError to
> > Foo::Error.  Take a look at TimeoutError vs Timeout::Error,
> > for example.
> >
> > Is there a reason the latter is preferred these days?  Just curious.
>
> Any thoughts? Anyone?
>
> Dan
>

My two best guesses would be:

1) shorter code -- from within the Timeout class you would have to write

    raise TimeoutError, "error message"

vs.

    raise Error, "error message"

So it could just be fewer keystrokes for the developer.  However, I
think the second guess has more merit.

2) smart use of namespaces

Putting the Error within the Timeout class namespace let's you quickly
identify which class defined the method that raised the exception.
For example

class A
  class Error < Exception; end
  def a() raise Error, "from #{self.class.name}"
end

class B < A
  class Error < Exception; end
  def b() raise Error, "from #{self.class.name}"
end

A.new.a
B.new.a
B.new.b

# -->  A::Error: from A
# -->  A::Error: from B
# -->  B::Error: from B

So, even though we invoke a() through and instance of B, the exception
tells us that the error came from one of A's methods.  The only catch
with this method is if B fails to define its own Error class.  Then
all exceptions will look like they're coming from A.

Any other thoughts out there?