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 (athena.apache.org: local policy)
Date: Thu, 16 Aug 2012 01:02:45 +0200
From: Gilles Sadowski <gilles@harfang.homelinux.org>
To: dev@commons.apache.org
Subject: Re: [math] assert policy
Message-ID: <20120815230245.GI24856@dusk.harfang.homelinux.org>
Mail-Followup-To: dev@commons.apache.org
References: <380-2201281604357653@M2W126.mail2web.com>
 <502804D1.8010802@yahoo.de>
 <225e609a26bf05284933bfa2444c5e87@nimp.co.uk>
 <2f3b5e787b725a8c8820a9c6548f327b@nimp.co.uk>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <2f3b5e787b725a8c8820a9c6548f327b@nimp.co.uk>
User-Agent: Mutt/1.5.21 (2010-09-15)
X-DCC-scarlet.be-Metrics: sif 20002; Body=1 Fuz1=1 Fuz2=1
X-Virus-Scanned: clamav-milter 0.97.1-exp at sif
X-Virus-Status: Clean
X-Virus-Checked: Checked by ClamAV on apache.org

On Wed, Aug 15, 2012 at 10:46:06PM +0200, matic wrote:
> Sebb, Gilles and I would like to start a discussion [...]
  ^^^^

It was not that "Sebb" who commented on MATH-845... ;-)

> [...]
> 
> @Gilles: sometimes assertion are a form of comments on steroid ->
> they will bark at you if you did not read them, and equally
> important: they are unambiguous. When I first write a method, it
> usually does not work right away. If it contains asserts, I usually
> get a clue of what's wrong, and if I don't, I try to write
> additional ones before tracking down the failure in a debug session.
> It is way faster, it forces me to understand better what I am coding
> (when I just follow a algorithm described in a paper, the typical
> situation for CM stuff) and the best of all: it will help anyone who
> later modify the code.
> -> in short, I see assertions as an invaluable tool to help
> developers, not just something to check input parameters in private
> methods. For this reason, I would support the following policy:
> 1. Use asserts as much as you like, but they are by no mean a
> substitute to runtime checks (code that throws "MathInternalError")
> for input parameters of public methods.
> 2. Asserts must be enabled in all unit tests

I don't deny that assertions can help you while developing, but the
algorithms in the CM library should not be construed as a "work in
progress". To be sure, quite a few areas definitely need all kinds of
improvements, but what I mean is that when something is checked in, it
should be working as expected (bugs notwithstanding) by the developer. That
means: "assert" statements will not be triggered. Unit tests should be
provided to ensure that everything (ideally) behaves as expected.

I understand that you did not mean to replace runtime check with assertions
but I'm a little afraid that "assert" will be considered enough (or better
than comments), such that the amount of comments will be reduced (while the
opposite should happen).
Moreover, "assert" generally checks "obvious" mistakes, which will happen
during development but are much less likely to occur when the finished code
is being called (I think). Once you start sprinkling "assert" statements in
a library like CM, it can quickly become littered with hundreds of them (in
fact there would probably be more "assert" than there are precondition
checks). I wondered how more readable that will make the code and for what
added value.
I understand that the readability would suffer (and even more) by
introducing logging statements all over the place, but at least that would
provide the benefit that one could be able to trace a bug to its root cause.
[I'm saying this because I recently wished I had logging inside a CM
alogrithm, while "assert" wouldn't have helped.]


Best regards,
Gilles

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