commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig McClanahan <craig...@apache.org>
Subject Re: [resources] Preparation for a Release Candidate
Date Fri, 25 Nov 2005 19:14:26 GMT
On 11/25/05, Niall Pemberton <niall.pemberton@gmail.com> wrote:
>
> On 11/25/05, Martin Cooper <martinc@apache.org> wrote:
> > On 11/24/05, Niall Pemberton <niall.pemberton@gmail.com> wrote:
> > >
> > > On 11/23/05, Martin Cooper <martinc@apache.org> wrote:
> > > > On 11/22/05, Niall Pemberton <niall.pemberton@blueyonder.co.uk>
> wrote:
> > > > >
> > > > > 1) Quite a few methods are declaring in the javadoc that they
> throw
> > > > > RuntimeExceptions, which are coming out on the checkstyle:
> > > > >
> http://jakarta.apache.org/commons/resources/checkstyle-report.html
> > > > >
> > > > > My preferenc is to removed these, but I can understand why they
> were
> > > put
> > > > > in.
> > > > > Opinions?
> > > >
> > > >
> > > > I think the code should say what it means. ;-) Looking at
> Resources.java
> > > ,
> > > > the init() and destroy() methods declare that they throw
> > > ResourcesException
> > > > (and Javadoc that). All of the other methods do not declare that
> they
> > > throw
> > > > that exception, but the Javadocs say they do. If they really do (or
> > > can),
> > > > then they should declare that. If they don't, then we should remove
> the
> > > > Javadocs.
> > >
> > > They can throw those exceptions, but since they're derived from
> > > RuntimeExceptions it doesn't make any difference wether they're in the
> > > method signature or not. I've changed my mind and think we should
> > > leave them as it is - the javadoc informs people that they can be
> > > thrown - whether they choose to handle them or not is up to them. Sun
> > > does the same kind of thing in java.util.ResourceBundle in java 1.4 -
> > > its getObject() method has Runtime exceptions in the javadoc, but not
> > > the method signature.
> >
> >
> > OK. Now what is the justification for the init and destroy methods in
> > Resources to explicitly state that they throw ResourcesException, but
> not
> > the other methods? That seems a little odd.
>
> I agree it is inconsistent so I'm not going to try and justify it. At
> the end of the day IMO it doesn't matter which way you go and its just
> a question of whether inconsistency in this case matters enough to
> change things. If the consensus is it does, my preference would be to
> change the init/detroy method signatures simply because that
> represents the least amount of work. If you (or anyone else) has a
> strong opinion on this, then I'll go with that and get this put to
> bed.


I've seen a trend in API design towards explicity documenting (in Javadocs)
the RuntimeExceptions that a method might throw, but not declaring the
"throws" clause (because the language doesn't require you to use try/catch
around calls to those methods).  My initial leaning would be towards this
(which would mean removing the throws on init/destroy) but leaving the docs
alone.

I'm definitely +1 we should be consistent throughout the API, though ... and
that we need to address this now and not later.


Niall


Craig


> --
> > Martin Cooper
> >
> >
> > Niall
> > >
> > > > My tuppence.
> > > >
> > > > --
> > > > Martin Cooper
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message