From dev-return-138441-apmail-commons-dev-archive=commons.apache.org@commons.apache.org Thu Sep 13 06:27:59 2012 Return-Path: X-Original-To: apmail-commons-dev-archive@www.apache.org Delivered-To: apmail-commons-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 5309CD207 for ; Thu, 13 Sep 2012 06:27:59 +0000 (UTC) Received: (qmail 51088 invoked by uid 500); 13 Sep 2012 06:27:59 -0000 Delivered-To: apmail-commons-dev-archive@commons.apache.org Received: (qmail 50736 invoked by uid 500); 13 Sep 2012 06:27:57 -0000 Mailing-List: contact dev-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Commons Developers List" Delivered-To: mailing list dev@commons.apache.org Received: (qmail 50699 invoked by uid 99); 13 Sep 2012 06:27:56 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 13 Sep 2012 06:27:56 +0000 X-ASF-Spam-Status: No, hits=2.0 required=5.0 tests=RCVD_IN_BL_SPAMCOP_NET,SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of SRS0=y7qJ=HM=m4x.org=sebastien.brisard@bounces.m4x.org designates 91.121.62.107 as permitted sender) Received: from [91.121.62.107] (HELO mx3.polytechnique.org) (91.121.62.107) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 13 Sep 2012 06:27:47 +0000 Received: from mx3.polytechnique.org (mx3 [91.121.62.107]) by ozgurluk.polytechnique.org (Postfix) with ESMTP id A56821E013B for ; Thu, 13 Sep 2012 08:27:24 +0200 (CEST) Received: from mx1.polytechnique.org (mx1 [129.104.30.34]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client CN "mx1.polytechnique.org", Issuer "Polytechnique.org" (verified OK)) by mx3.polytechnique.org (Postfix) with ESMTPS id 93E711E0138 for ; Thu, 13 Sep 2012 08:27:24 +0200 (CEST) Received: from mail-ie0-f171.google.com (mail-ie0-f171.google.com [209.85.223.171]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) (No client certificate requested) by ssl.polytechnique.org (Postfix) with ESMTPSA id C4AF314085763 for ; Thu, 13 Sep 2012 08:27:23 +0200 (CEST) Received: by ieje14 with SMTP id e14so5520710iej.30 for ; Wed, 12 Sep 2012 23:27:22 -0700 (PDT) MIME-Version: 1.0 Received: by 10.50.95.231 with SMTP id dn7mr953787igb.37.1347517642454; Wed, 12 Sep 2012 23:27:22 -0700 (PDT) Received: by 10.64.141.167 with HTTP; Wed, 12 Sep 2012 23:27:22 -0700 (PDT) Date: Thu, 13 Sep 2012 08:27:22 +0200 Message-ID: Subject: [math] Documenting exceptions in interfaces (MATH-854) From: =?ISO-8859-1?Q?S=E9bastien_Brisard?= To: Commons Developers List Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable X-AV-Checked: ClamAV using ClamSMTP at svoboda.polytechnique.org (Thu Sep 13 08:27:24 2012 +0200 (CEST)) X-Org-Mail: sebastien.brisard.1997@polytechnique.org X-Virus-Checked: Checked by ClamAV on apache.org X-Old-Spam-Flag: No, tests=bogofilter, spamicity=0.000000, queueID=19DC614085790 Dear all, in previous discussions, it was decided that Interfaces (and, I suppose abstract methods) should *not* have a throws clause. So, yesterday, I started modifying the javadoc of FieldVector. Each "throws" clause was simply replaced by the following statement "Implementations should throw [...] if [...]". Please have a look to FieldVector and ArrayFieldVector for clarity. This has several drawbacks 1. The javadoc of implementations must grow, since the implementer must write something like /** * {@inheritDoc} * * @throws DimensionMismatchException if {@code v} is not the same size= as * {@code this}. */ instead of simply writing /** {@inheritDoc} */. 2. The resulting javadoc of implementations is not satisfactory. For example, the javadoc of FieldVector.add(FieldVecto v) now reads // Begin Javadoc Compute the sum of this and v. Implementations should throw DimensionMismatchException if v is not the same size as this. Specified by: add in interface FieldVector> Parameters: v - vector to be added Returns: this + v Throws: DimensionMismatchException - if v is not the same size as this. // End javadoc The "should throw" statement should really not be here, but it is too much of a hassle to rewrite the whole javadoc comment for each implementation. 3. Using Luc's trick brings a whole lot of error messages // Begin error message Exception MathXxxException is not compatible with throws clause in [...] // End error message this is not really a problem, but it makes the whole process of populating the throws clauses a bit difficult. 4. More importantly, there is *no way* to ensure that we actually document all exceptions. Indeed, if we take for example FieldVector.mapDivide(T d) The only reason we know we *have* to add MathArithmeticException to the throws clause is because FieldElement (which is an interface) *specifies* this exception in the throws clause of FieldElement.divide(). If this throws clause is removed from interfaces, then LUC'S TRICK becomes useless. [1] For all these reasons, I would advocate *specifying* in interfaces exceptions which we know must occur. For example, DimensionMismatchException will be in the signature of *all* implementations of FieldVector.add(FieldVector). Why not add it to the throws clause? The answer is likely to be "because it is bad practice", but I think advertising unchecked exceptions is already a bad practice. So I think if we go for a bad practice anyway, we should do it *only if it makes our lives easier*. I don't think the current state does. On a more personal side, I'd like to say that I'm getting tired of this issue. I have been working for days on the linear package, but I'm making no progress, because each time I commit a change, I realize this was not the proper thing to do because of new exchanges on the ML. So I keep going back and forth. This is really sucking all of my C-M time, while I'd like to be working on other issues (eg special functions Gamma and Beta, visitors for FieldVectors, ...). That would be perfectly fine if I could see the benefit of MATH-854. While this seemed a good idea when we started discussing it, I'm not sure anymore, now that we have really tried to implement MATH-854. I'm sure that I'm not the only one among the regular developers to spend so much time on this issue. Our powers are limited, and I really would rather we had more time to concentrate on real (meaning, numerical) issues. S=E9bastien [1] MathArithmeticException in FieldElement.divide(FieldElement) is probably not the best example, as Gilles noted inconsistencies (Decimal64 and Complex do not throw an exception, but return NaN instead). --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org For additional commands, e-mail: dev-help@commons.apache.org