Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (nike.apache.org: local policy)
Date: Fri, 5 Nov 2010 17:32:10 +0100 (CET)
From: luc.maisonobe@free.fr
To: Commons Developers List <dev@commons.apache.org>
Message-ID: 
 <186523983.2776611288974730457.JavaMail.root@spooler6-g27.priv.proxad.net>
In-Reply-To: <20101105152005.GP4919@dusk.harfang.homelinux.org>
Subject: Re: svn commit: r1030464 [1/3] - in /commons/proper/math/trunk/src:
 main/java/org/apache/commons/math/
 main/java/org/apache/commons/math/analysis/
 main/java/org/apache/commons/math/analysis/integration/
 main/java/org/apache/commons/math/analysis/inte
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable


----- "Gilles Sadowski" <gilles@harfang.homelinux.org> a =C3=A9crit :

> Hello.
>=20
> > >> So go ahead with the change, removing the throws from the
> declaration but keeping the javadoc as suggested previously.
> > >
> > > Again, what is it that you try to convey by specifying a single
> exception in
> > > the Javadoc? Any unchecked exception can be thrown from a class
> that
> > > implement the interface.
> > > If the user code doesn't care that the evaluation fails, it should
> catch
> > > everything and continue. Alternatively, if it cannot continue, it
> should let
> > > the exception propagate. In either case, there isn't any useful
> information
> > > from a Javadoc "@throws" tag: We already know that unchecked
> exceptions can
> > > arise.
> >=20
> > I don't know if it's relevant here, but it's standard practice in
> lots
> > of code I've seen to document unchecked exceptions in the @throws
> > block if your code explicitly throws it.
>=20
> This would be the minimum, but it seems that CM tries to be better in
> that
> it aims at also documenting the exceptions thrown from the called
> code.

No. We try to explain what the user could throw or rather provide guideline=
s
on what to throw.

> Of course it is more work on the part of the developer and also more
> difficult do check for consistency when reading the code (short of
> following
> all the calls).

Yes, and it what I like in checked exception, but I will not come back to t=
his
discussion, now we use unchecked exception, so we document them.

Luc

>=20
> > However I would not put this
> > tag on the interface method declaration, because maybe some
> > implementation doesn't throw that exception. [...]
>=20
> +1
>=20
>=20
> Best,
> Gilles
>=20
>=20
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org