You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Stephen Colebourne <sc...@btopenworld.com> on 2004/05/15 01:47:02 UTC
[math] Design review pre 1.0
I have performed a lightweight review of [math] from a code/style POV (not
technically as I'm not mathematical...)
1) Remember your public API that you must maintain includes both public and
protected classes/methods/fields. Are you confident that every method/field
(especially fields) are correctly and suitably named for you to want to
keep?
2) Wherever there is implements Serializable you should have a
serialVersionUID static field. And are you confident that the
implementations are well enough established to allow for serialization? What
about transient fields? Serialization is definitely not about adding the
implements clause to everything.
3) Javadocs are sometimes thin. On occasions, they are written as paragraphs
visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
missing, eg StandardDeviation
4) You might want to consider separating interfaces from implementations.
Perhaps all interfaces in the base package, or impl subpackages. Then again
the current layout may be best.
5) Is double suitable for these calculations? Should the strictfp flag be
used? (I have no idea as to the answer, but I have to ask)
6) ComplexFormat doesn't extend the JDK Format class
7) ComplexMath is a utils class, which would be named ComplexMathUtils in
lang or collections (although the JDK Math class sets an alternate
precedent) The constructor is private, which I would recommend is changed to
public (aids tools like Velocity). Also Beta/Erf/Gamma.
8) @author tags are often missing
9) Factorys use the method newInstance() to obtain an instance -
getInstance() seems more typical of commons, and allows you to return a
cached value.
10) SummaryStatistics/DescriptiveStatistics are factories but aren't named
as such. They also use Class.forName() which is dubious in a class loader
environment.
11) Ensure there are no TODO comments in the Javadoc (OK in code) For
example GammaDistributionImpl
12) Should EmpiricalDistribution really have methods taking File and String
filePath - is File not enough? The implementation actually seems to do
something different (beware file encodings)
13) Ensure every class has a constructor - never rely on the auto generated
one, for example BivariateRegression
14) Some import statements are rather screwed visually, eg Product
15) Dependencies!!!!
commons-discovery can and should be an optional dependency. In fact it may
already be, as each call to DiscoveryClass is in an Exception catch, which
ought to trap ClassNotFoundException. However, I don't think that the
default implementation behaviour is actually working which needs fixing.
commons-lang is only used for NestableException. This is a dubious
dependency - the relevant code can be copied, and [lang]s ExceptionUtils is
perfectly able to handle extracting cause parameters by reflection. (Don't
copy NestableException - copy the code within)
commons-logging is not used directly, just via beanutils and discovery (and
is a classic example of commons chained dependencies that should be avoided)
commons-beanutils doesn't seem to be used, so shouldn't be in project xml
commons-collections TreeBag is used by Frequency - it might be worth
considering removing this dependency, but it is the hardest.
(CollectionUtils.NATURAL_COMPARATOR is a simple class to copy)
Anyway, I hope this focuses attention on what needs doing (boring-wise)
before 1.0.
Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Design review pre 1.0
Posted by "Mark R. Diggory" <md...@latte.harvard.edu>.
Mark R. Diggory wrote:
>> 10) SummaryStatistics/DescriptiveStatistics are factories but aren't
>> named
>> as such.
I wanted to add a comment here, these are not "Factories", they are
Interfaces which instantiate a selected underlying implementation.
Neither of these actually expose the objects they instantiate. So naming
the "Factories" would be a misnomer.
-Mark
--
Mark Diggory
Software Developer
Harvard MIT Data Center
http://www.hmdc.harvard.edu
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Design review pre 1.0
Posted by "Mark R. Diggory" <md...@latte.harvard.edu>.
I want to review this list and add in my comments...
Stephen Colebourne wrote:
>I have performed a lightweight review of [math] from a code/style POV (not
>technically as I'm not mathematical...)
>
>1) Remember your public API that you must maintain includes both public and
>protected classes/methods/fields. Are you confident that every method/field
>(especially fields) are correctly and suitably named for you to want to
>keep?
>
>
>
Yes, this could stand a code review ( 1 hour with report to list? )
>2) Wherever there is implements Serializable you should have a
>serialVersionUID static field. And are you confident that the
>implementations are well enough established to allow for serialization? What
>about transient fields? Serialization is definitely not about adding the
>implements clause to everything.
>
>
>
See serialization thread concerning resolving any stray serialization
issues.
>3) Javadocs are sometimes thin. On occasions, they are written as paragraphs
>visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
>missing, eg StandardDeviation
>
>
>
Yes, it would be good to maintain acceptable html in javadoc. Yet, I'd
like to point out that javadoc isn't java code. while we would like to
maintain lots of it to help our users understand it, the library works
just fine without it.
>4) You might want to consider separating interfaces from implementations.
>Perhaps all interfaces in the base package, or impl subpackages. Then again
>the current layout may be best.
>
>
>
I'm not convinced we are at the point where this is possible. Though its
open to discussion. Some areas this may be easier than others
(distributions, analysis). Some packages are rather small and sparse,
this would make them even sparser (Complex). I've put considerable
effort into separating the the UnivariateStatistics interfaces from the
actuall implementations. Just as a side note, at this time separation
into implementations and interfaces should not mean two different jars
as it is general Commons practice to try to maintain a project as one
distributable jar.
>5) Is double suitable for these calculations? Should the strictfp flag be
>used? (I have no idea as to the answer, but I have to ask)
>
>
>
Neither do I. Can anyone enlighten us?
>6) ComplexFormat doesn't extend the JDK Format class
>
>7) ComplexMath is a utils class, which would be named ComplexMathUtils in
>lang or collections (although the JDK Math class sets an alternate
>precedent) The constructor is private, which I would recommend is changed to
>public (aids tools like Velocity). Also Beta/Erf/Gamma.
>
>
>
And throughout the Math package we use this naming "StatUtils",
"MathUtils". Maybe it should just be "ComplexUtils".
I'm unsure about instantiating StaticUtils, does velocity actually call
staic methods on instantiated objects? Doesn't this seem a bad behavior
to promote?
>8) @author tags are often missing
>
>
>
Development Team Decision, we do not want @author tags, developers and
contributors are acnowledged in Maven project.xml and site docs.
>9) Factorys use the method newInstance() to obtain an instance -
>getInstance() seems more typical of commons, and allows you to return a
>cached value.
>
>
>
There is a symantic difference here:
"getInstance" is ideal for singleton instances
"newInstance" is ideal for instantiation of new instances (See w3c DOM, SAX)
Somewhere along the line we introduced "createFooBar", for cases where a
Factory creates multiple types of objects other than itself.
I can accept these naming conventions. They are not uncommon.
>10) SummaryStatistics/DescriptiveStatistics are factories but aren't named
>as such. They also use Class.forName() which is dubious in a class loader
>environment.
>
>
>
True, its a toss up, there are alot of service discovery approaches. do
we want to be dependent on the Discovery API, or just use the Java
services mechanism and jar each implementation such that it can be
"discovered"?
>11) Ensure there are no TODO comments in the Javadoc (OK in code) For
>example GammaDistributionImpl
>
>12) Should EmpiricalDistribution really have methods taking File and String
>filePath - is File not enough? The implementation actually seems to do
>something different (beware file encodings)
>
>
>
I would argue not that alternate method signatures are unneccessary,
they are assistive and offer options for coding, but that the methods
should be organized to use only one implementation of a loading strategy. ie
public void load(URl url);
public void load(File file);
public void load(InputStream);
here InputStream is the method that actually implements the loading
behavior and the other two signatures simply aquire an InputStream and
pass it to the InputStream signature. Unfortunately, the way the
implementation is designed such that it reads each url/file twice makes
doing this not possible.
>13) Ensure every class has a constructor - never rely on the auto generated
>one, for example BivariateRegression
>
>
>
Good Point
>14) Some import statements are rather screwed visually, eg Product
>
>
>
These are formated using Eclipse configured to meet Sun formating
standards. I assume this formating is caused when the package name gets
long. I've maintained it for consistency.
>15) Dependencies!!!!
>commons-discovery can and should be an optional dependency. In fact it may
>already be, as each call to DiscoveryClass is in an Exception catch, which
>ought to trap ClassNotFoundException. However, I don't think that the
>default implementation behaviour is actually working which needs fixing.
>
>
>
We need a good, standard discover mechanism. it sucks to have to copy
and reimplement when other commons developers are already creating such
excellent code. I know we want to keep dependencies to a minimum, but
code reuse is also important, then point of Commons is to reduce code
replication.
>commons-lang is only used for NestableException. This is a dubious
>dependency - the relevant code can be copied, and [lang]s ExceptionUtils is
>perfectly able to handle extracting cause parameters by reflection. (Don't
>copy NestableException - copy the code within)
>
>
>
I actually agree here because this class was created just to provide
Nestability to older JVM's. Its really just a "patch" until time renders
those JVM's obsolete. The code would eventually be removed from the Math
API.
>commons-logging is not used directly, just via beanutils and discovery (and
>is a classic example of commons chained dependencies that should be avoided)
>
>
>
Yes, I had worked to make it a test and compile time dependency only.
>commons-beanutils doesn't seem to be used, so shouldn't be in project xml
>
>
>
Its a test, compile time dependency for BeanListUnivariate, not a
runtime dependency.
>commons-collections TreeBag is used by Frequency - it might be worth
>considering removing this dependency, but it is the hardest.
>(CollectionUtils.NATURAL_COMPARATOR is a simple class to copy)
>
>
>
I'm not adverse to maintaing it, this is a Complex Datastructure, I'd
rather reley on those who thought it out supporting it, Math shouldn't
be about Collections.
>Anyway, I hope this focuses attention on what needs doing (boring-wise)
>before 1.0.
>
>Stephen
>
>
I'd like us not to get too bound up in the dependency issue. If they can
esily be removed, great, if they are to access complex datstructures and
behavior, lets let those experts maintain such tools and we promote
thier reuse. I would really classify Math as a secondary level Commons
package. It does some complex things for which the Collections
dependencies can be deemed acceptable and appropriate.
-Mark
Re: [math] Design review pre 1.0
Posted by Al Chou <ho...@yahoo.com>.
--- Stephen Colebourne <sc...@btopenworld.com> wrote:
> Congratulations on the work put into [math]!
>
> Stephen
>
> ----- Original Message -----
> From: "Phil Steitz" <ph...@steitz.com>
> To: "Jakarta Commons Developers List" <co...@jakarta.apache.org>
> Sent: Sunday, July 25, 2004 7:13 PM
> Subject: Re: [math] Design review pre 1.0
>
> > Updated response interspersed. Pls correct / comment as necessary...
Yes, many thanks to Phil for so much work done! I'm sorry I haven't had time
to contribute more.
Al
=====
Albert Davidson Chou
Get answers to Mac questions at http://www.Mac-Mgrs.org/ .
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Design review pre 1.0
Posted by Stephen Colebourne <sc...@btopenworld.com>.
Congratulations on the work put into [math]!
Stephen
----- Original Message -----
From: "Phil Steitz" <ph...@steitz.com>
To: "Jakarta Commons Developers List" <co...@jakarta.apache.org>
Sent: Sunday, July 25, 2004 7:13 PM
Subject: Re: [math] Design review pre 1.0
> Updated response interspersed. Pls correct / comment as necessary...
>
> Stephen Colebourne wrote:
> > I have performed a lightweight review of [math] from a code/style POV
(not
> > technically as I'm not mathematical...)
> >
> > 1) Remember your public API that you must maintain includes both public
and
> > protected classes/methods/fields. Are you confident that every
method/field
> > (especially fields) are correctly and suitably named for you to want to
> > keep?
>
> Let's just say we have done our best ;-)
> >
> > 2) Wherever there is implements Serializable you should have a
> > serialVersionUID static field. And are you confident that the
> > implementations are well enough established to allow for serialization?
What
> > about transient fields? Serialization is definitely not about adding the
> > implements clause to everything.
>
> All serializable classes have serialVersionUIDs. Some serialization
> incompatible changes may be introduced in .x releases (prior to 2.0); but
> the current impls work correctly and have working tests.
> >
> > 3) Javadocs are sometimes thin. On occasions, they are written as
paragraphs
> > visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
> > missing, eg StandardDeviation
>
> Javadocs have been improved and formatting fixed. Class javadoc may be
> thin for classes that just implement a simple interface (e.g. some of the
> distribution classes); but method javadoc is complete. User Guide is also
> now complete.
> >
> > 4) You might want to consider separating interfaces from
implementations.
> > Perhaps all interfaces in the base package, or impl subpackages. Then
again
> > the current layout may be best.
>
> Decided not to separate within packages.
> >
> > 5) Is double suitable for these calculations? Should the strictfp flag
be
> > used? (I have no idea as to the answer, but I have to ask)
>
> Decided to wait on adding strictfp support to later release, as if we do
> this, users should be able to choose, since performance impact can be
> significant.
> >
> > 6) ComplexFormat doesn't extend the JDK Format class
>
> Fixed.
> >
> > 7) ComplexMath is a utils class, which would be named ComplexMathUtils
in
> > lang or collections (although the JDK Math class sets an alternate
> > precedent)
>
> Fixed
>
> The constructor is private, which I would recommend is changed to
> > public (aids tools like Velocity). Also Beta/Erf/Gamma.
>
> Not changed (no consensus to change).
> >
> > 8) @author tags are often missing
>
> Not changed (consensus is no author tags). If "anonymous" tags are j-c
> standard, need to write a script to add these.
> >
> > 9) Factorys use the method newInstance() to obtain an instance -
> > getInstance() seems more typical of commons, and allows you to return a
> > cached value.
>
> Factories are dynamically configurable, so consensus was to let the client
> handle caching factory instances (stay with newInstance() semantics).
> Internal clients have been changed to cache (default) factory instances.
> >
> > 10) SummaryStatistics/DescriptiveStatistics are factories but aren't
named
> > as such.
>
> Consensus was that these are not really factories, so names have not been
> changed.
>
> They also use Class.forName() which is dubious in a class loader
> > environment.
>
> Fixed.
> >
> > 11) Ensure there are no TODO comments in the Javadoc (OK in code) For
> > example GammaDistributionImpl
>
> Fixed
> >
> > 12) Should EmpiricalDistribution really have methods taking File and
String
> > filePath - is File not enough? The implementation actually seems to do
> > something different (beware file encodings)
> >
> Fixed.
>
> > 13) Ensure every class has a constructor - never rely on the auto
generated
> > one, for example BivariateRegression
>
> Fixed.
> >
> > 14) Some import statements are rather screwed visually, eg Product
> >
> Fixed.
>
> > 15) Dependencies!!!!
>
> No (hard) runtime dependencies left. [discovery] and [logging] are
> required to compile [math] and to use the factory configuration features
> that they support. Factory methods that use [discovery] have been modified
> to catch NoClassDefFound and return instances of default implementations.
>
> Phil
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Design review pre 1.0
Posted by Phil Steitz <ph...@steitz.com>.
Updated response interspersed. Pls correct / comment as necessary...
Stephen Colebourne wrote:
> I have performed a lightweight review of [math] from a code/style POV (not
> technically as I'm not mathematical...)
>
> 1) Remember your public API that you must maintain includes both public and
> protected classes/methods/fields. Are you confident that every method/field
> (especially fields) are correctly and suitably named for you to want to
> keep?
Let's just say we have done our best ;-)
>
> 2) Wherever there is implements Serializable you should have a
> serialVersionUID static field. And are you confident that the
> implementations are well enough established to allow for serialization? What
> about transient fields? Serialization is definitely not about adding the
> implements clause to everything.
All serializable classes have serialVersionUIDs. Some serialization
incompatible changes may be introduced in .x releases (prior to 2.0); but
the current impls work correctly and have working tests.
>
> 3) Javadocs are sometimes thin. On occasions, they are written as paragraphs
> visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
> missing, eg StandardDeviation
Javadocs have been improved and formatting fixed. Class javadoc may be
thin for classes that just implement a simple interface (e.g. some of the
distribution classes); but method javadoc is complete. User Guide is also
now complete.
>
> 4) You might want to consider separating interfaces from implementations.
> Perhaps all interfaces in the base package, or impl subpackages. Then again
> the current layout may be best.
Decided not to separate within packages.
>
> 5) Is double suitable for these calculations? Should the strictfp flag be
> used? (I have no idea as to the answer, but I have to ask)
Decided to wait on adding strictfp support to later release, as if we do
this, users should be able to choose, since performance impact can be
significant.
>
> 6) ComplexFormat doesn't extend the JDK Format class
Fixed.
>
> 7) ComplexMath is a utils class, which would be named ComplexMathUtils in
> lang or collections (although the JDK Math class sets an alternate
> precedent)
Fixed
The constructor is private, which I would recommend is changed to
> public (aids tools like Velocity). Also Beta/Erf/Gamma.
Not changed (no consensus to change).
>
> 8) @author tags are often missing
Not changed (consensus is no author tags). If "anonymous" tags are j-c
standard, need to write a script to add these.
>
> 9) Factorys use the method newInstance() to obtain an instance -
> getInstance() seems more typical of commons, and allows you to return a
> cached value.
Factories are dynamically configurable, so consensus was to let the client
handle caching factory instances (stay with newInstance() semantics).
Internal clients have been changed to cache (default) factory instances.
>
> 10) SummaryStatistics/DescriptiveStatistics are factories but aren't named
> as such.
Consensus was that these are not really factories, so names have not been
changed.
They also use Class.forName() which is dubious in a class loader
> environment.
Fixed.
>
> 11) Ensure there are no TODO comments in the Javadoc (OK in code) For
> example GammaDistributionImpl
Fixed
>
> 12) Should EmpiricalDistribution really have methods taking File and String
> filePath - is File not enough? The implementation actually seems to do
> something different (beware file encodings)
>
Fixed.
> 13) Ensure every class has a constructor - never rely on the auto generated
> one, for example BivariateRegression
Fixed.
>
> 14) Some import statements are rather screwed visually, eg Product
>
Fixed.
> 15) Dependencies!!!!
No (hard) runtime dependencies left. [discovery] and [logging] are
required to compile [math] and to use the factory configuration features
that they support. Factory methods that use [discovery] have been modified
to catch NoClassDefFound and return instances of default implementations.
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Design review pre 1.0
Posted by "Mark R. Diggory" <md...@latte.harvard.edu>.
Stephen,
This ROCKS, but its going to take me all weekend to respond
accurately... ;-) I have some interesting comments for many of these issues.
-Mark
Stephen Colebourne wrote:
>I have performed a lightweight review of [math] from a code/style POV (not
>technically as I'm not mathematical...)
>
>1) Remember your public API that you must maintain includes both public and
>protected classes/methods/fields. Are you confident that every method/field
>(especially fields) are correctly and suitably named for you to want to
>keep?
>
>2) Wherever there is implements Serializable you should have a
>serialVersionUID static field. And are you confident that the
>implementations are well enough established to allow for serialization? What
>about transient fields? Serialization is definitely not about adding the
>implements clause to everything.
>
>3) Javadocs are sometimes thin. On occasions, they are written as paragraphs
>visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
>missing, eg StandardDeviation
>
>4) You might want to consider separating interfaces from implementations.
>Perhaps all interfaces in the base package, or impl subpackages. Then again
>the current layout may be best.
>
>5) Is double suitable for these calculations? Should the strictfp flag be
>used? (I have no idea as to the answer, but I have to ask)
>
>6) ComplexFormat doesn't extend the JDK Format class
>
>7) ComplexMath is a utils class, which would be named ComplexMathUtils in
>lang or collections (although the JDK Math class sets an alternate
>precedent) The constructor is private, which I would recommend is changed to
>public (aids tools like Velocity). Also Beta/Erf/Gamma.
>
>8) @author tags are often missing
>
>9) Factorys use the method newInstance() to obtain an instance -
>getInstance() seems more typical of commons, and allows you to return a
>cached value.
>
>10) SummaryStatistics/DescriptiveStatistics are factories but aren't named
>as such. They also use Class.forName() which is dubious in a class loader
>environment.
>
>11) Ensure there are no TODO comments in the Javadoc (OK in code) For
>example GammaDistributionImpl
>
>12) Should EmpiricalDistribution really have methods taking File and String
>filePath - is File not enough? The implementation actually seems to do
>something different (beware file encodings)
>
>13) Ensure every class has a constructor - never rely on the auto generated
>one, for example BivariateRegression
>
>14) Some import statements are rather screwed visually, eg Product
>
>15) Dependencies!!!!
>commons-discovery can and should be an optional dependency. In fact it may
>already be, as each call to DiscoveryClass is in an Exception catch, which
>ought to trap ClassNotFoundException. However, I don't think that the
>default implementation behaviour is actually working which needs fixing.
>
>commons-lang is only used for NestableException. This is a dubious
>dependency - the relevant code can be copied, and [lang]s ExceptionUtils is
>perfectly able to handle extracting cause parameters by reflection. (Don't
>copy NestableException - copy the code within)
>
>commons-logging is not used directly, just via beanutils and discovery (and
>is a classic example of commons chained dependencies that should be avoided)
>
>commons-beanutils doesn't seem to be used, so shouldn't be in project xml
>
>commons-collections TreeBag is used by Frequency - it might be worth
>considering removing this dependency, but it is the hardest.
>(CollectionUtils.NATURAL_COMPARATOR is a simple class to copy)
>
>
>Anyway, I hope this focuses attention on what needs doing (boring-wise)
>before 1.0.
>
>Stephen
>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>
Re: [math] Dependencies WAS: Design review pre 1.0
Posted by "Mark R. Diggory" <md...@latte.harvard.edu>.
Yes, I had placed it into test a while back which reduced it to a build
time dependency as opposed to a runtime dependency. Originally, I was
attempting to isolate this as an example as opposed to a Class which
users would utilize, so I was working hard to remove it from the
distribution jar.
All beanutils is benefiting us with is a "NumberTransformer" that was
easy to write. This could/should be made somewhat plugable. Right now
BeanUtils usage is in an anonymous NumberTransformer innerclass within
BeanListUnivariateImpl:
new NumberTransformer() {
/**
* @see
org.apache.commons.math.util.NumberTransformer#transform(java.lang.Object)
*/
public double transform(final Object o) throws MathException {
try {
return (
(Number) PropertyUtils.getProperty(
o,
getPropertyName()))
.doubleValue();
} catch (IllegalAccessException e) {
throw new MathException(
"IllegalAccessException in Transformation: "
+ e.getMessage(),
e);
} catch (InvocationTargetException e) {
throw new MathException(
"InvocationTargetException in Transformation: "
+ e.getMessage(),
e);
} catch (NoSuchMethodException e) {
throw new MathException(
"oSuchMethodException in Transformation: "
+ e.getMessage(),
e);
}
}
};
-Mark
Tim O'Brien wrote:
>Phil Wrote....
>
>
>
>>commons-beanutils doesn't seem to be used, so shouldn't be in project
>>xml
>>
>>
>
>BeanUils is used in the "BeanList" stuff that I recently rectified but have
>not moved back into src from test. I guess I am in favor of relegating this
>to experimental and dropping the dependency for 1.0.
>
>[Tim O'Brien]
>
>Yes, 100% go for it. I wonder if we can release a supplemental (separate)
>deliverable that would provide some less important utilities that needed
>these dependencies.
>
>In other words, a core math library with zero or one dependency, and a
>supplemental that adds capabilities that depend on other commons libraries.
>
>
>Confusing or interesting: What do you think?
>
>Tim
>
>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>
RE: [math] Dependencies WAS: Design review pre 1.0
Posted by Tim O'Brien <to...@discursive.com>.
Phil Wrote....
>
> commons-beanutils doesn't seem to be used, so shouldn't be in project
> xml
BeanUils is used in the "BeanList" stuff that I recently rectified but have
not moved back into src from test. I guess I am in favor of relegating this
to experimental and dropping the dependency for 1.0.
[Tim O'Brien]
Yes, 100% go for it. I wonder if we can release a supplemental (separate)
deliverable that would provide some less important utilities that needed
these dependencies.
In other words, a core math library with zero or one dependency, and a
supplemental that adds capabilities that depend on other commons libraries.
Confusing or interesting: What do you think?
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
[math] Dependencies WAS: Design review pre 1.0
Posted by Phil Steitz <ph...@steitz.com>.
Given all of the recent discussion of dependencies among commons
components, I think we should take a more conservative approach than we
have up to now, duplicating some code / functionality in a few place to
limit dependencies. If we do all of the things below, we will have no
hard dependencies.
>
> 15) Dependencies!!!! commons-discovery can and should be an optional
> dependency. In fact it may already be, as each call to DiscoveryClass
> is in an Exception catch, which ought to trap ClassNotFoundException.
> However, I don't think that the default implementation behaviour is
> actually working which needs fixing.
I agree with Stephen here, if we catch the ClassNotFoundException and just
create a default instance, [discovery] and hence [logging] can be
optional. I also agree with the "getInstance" vs. "newInstance"
semantics, returning cached instances to limit overhead when discovery is
used.
>
> commons-lang is only used for NestableException. This is a dubious
> dependency - the relevant code can be copied, and [lang]s
> ExceptionUtils is perfectly able to handle extracting cause parameters
> by reflection. (Don't copy NestableException - copy the code within)
I think this where we were going originally. We can eliminate the [lang]
dependency by duplicating a small amount of code. I am in favor of this.
>
> commons-logging is not used directly, just via beanutils and discovery
> (and is a classic example of commons chained dependencies that should
> be avoided)
Yes, can be made optional.
>
> commons-beanutils doesn't seem to be used, so shouldn't be in project
> xml
BeanUils is used in the "BeanList" stuff that I recently rectified but
have not moved back into src from test. I guess I am in favor of
relegating this to experimental and dropping the dependency for 1.0.
>
> commons-collections TreeBag is used by Frequency - it might be worth
> considering removing this dependency, but it is the hardest.
> (CollectionUtils.NATURAL_COMPARATOR is a simple class to copy)
Frequency originally just used a HashMap; but the TreeBag implementation
is better. This may be painful, but I will have a look at it.
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
RE: [math] Design review pre 1.0
Posted by Tim O'Brien <to...@discursive.com>.
> -----Original Message-----
> From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
> 6) ComplexFormat doesn't extend the JDK Format class
[Tim O'Brien]
Good catch, this makes sense, and it is now has the milestone of being the
29,000th Bugzilla issue.
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Design review pre 1.0
Posted by Phil Steitz <ph...@steitz.com>.
Tim O'Brien wrote:
>
>>-----Original Message-----
>>From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
>>3) Javadocs are sometimes thin. On occasions, they are written as
>>paragraphs
>>visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
>>missing, eg StandardDeviation
>
> [Tim O'Brien]
>
> Agree, JavaDocs are somewhat thin and in some cases we just reference some
> other web site. (i.e. ComplexMath simply has a URL:
> http://myweb.lmu.edu/dmsmith/ZMLIB.pdf ). A good benchmark to use is
> Digester, our "users" should be able to use a commons component without
> needing to look at the source, and having fuller JavaDoc goes a long way
> towards this goal.
I agree that users should be able to effectively use any commons component
without looking at the source and that means (among other things) in
[math] we need to include or reference full definitions and algorithm
descriptions for everything. Given the nature of mathematical definitions
(lots of dependencies :-), however, I do not think that it is feasible or
desirable to include full definitions of everything embedded in the
javadoc. My HO is that a link to a (stable, authoritative) reference and
sticking with standard terminology is better than trying to embed too much
math in the javadoc.
+1 to opening tickets pointing to the "thin" or garbled stuff, though.
Phil
>
> So, be warned, I'm using Bugzilla as a task list.
>
> Tim
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
RE: [math] Design review pre 1.0
Posted by Tim O'Brien <to...@discursive.com>.
> -----Original Message-----
> From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
> 3) Javadocs are sometimes thin. On occasions, they are written as
> paragraphs
> visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
> missing, eg StandardDeviation
[Tim O'Brien]
Agree, JavaDocs are somewhat thin and in some cases we just reference some
other web site. (i.e. ComplexMath simply has a URL:
http://myweb.lmu.edu/dmsmith/ZMLIB.pdf ). A good benchmark to use is
Digester, our "users" should be able to use a commons component without
needing to look at the source, and having fuller JavaDoc goes a long way
towards this goal.
So, be warned, I'm using Bugzilla as a task list.
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org