Hi all,
I'm forwarding a conversation I had with Gilles on the project structure for
the new commons-geometry project in order to get feedback on it from everyone.
Basically, Gilles is proposing (and has initially set up) a multi-module
project with the following modules so far:
* commons-geometry-bsp
* commons-geometry-euclidean-oned
* commons-geometry-euclidean-twod
* commons-geometry-euclidean-threed
My thought was that this module break up is too fine-grain and would make
development of code that uses more than one dimension more difficult than it
should be. I was initially picturing having a single project for all of the
current geometry code since it's all so closely related and there's not much of
it. However, I can see where Gilles is coming from with the previous experience
on commons-math. So, I'd like to propose an alternative module break up, one
that keeps all of the basic euclidean primitives in one place:
* commons-geometry-core -- This would contain the code currently in the
packages
* o.a.c.m.geometry
* o.a.c.m.partitioning
* o.a.c.m.geometry.euclidean.oned
* o.a.c.m.geometry.euclidean.twod
* o.a.c.m.geometry.euclidean.threed
* o.a.c.m.geometry.hull
* o.a.c.m.geometry.twod.hull
* o.a.c.m.geometry.enclosing (this is the odd-ball in the group here so
I could be convinced to put this elsewhere)
* commons-geometry-spherical -- This would contain
* o.a.c.m.geometry.spherical.oned
* o.a.c.m.geometry.spherical.twod
Basically, core would contain the main geometry interfaces (eg, Point, Space,
Vector) as well as all of the basic euclidean functionality. Most users would
only ever need to pull in this module. The other modules would be for other
spaces, such as spherical, and other special-purpose code that we have yet to
develop.
Thoughts?
Thanks,
Matt Juntunen
________________________________________
From: Gilles <gil...@harfang.homelinux.org>
Sent: Saturday, April 7, 2018 6:39 PM
To: Matt Juntunen
Subject: Re: Commons Geometry Project Structure
Hi Matt.
On Sat, 7 Apr 2018 16:01:32 +0000, Matt Juntunen wrote:
> Hi Gilles,
>
> Yes, I'm picturing a few possible issues with the current structure.
> First, I think that splitting everything up into modules at this
> point
> will inhibit development. For example, each time we add a new
> feature,
> we'll need to worry about either creating a new module or making it
> fit into existing modules. For example, if we make a general utility
> class that makes use of 1D, 2D, and 3D, we'd need to make a separate
> module for it so that it can pull in all of the other dimension
> modules.
Yes. No problem then?
> It wouldn't make sense to put it into 3D since it wouldn't
> just be 3D. This is actually the case with the GeometryTestUtils
> class
> I wrote.
>
> Also, the code may be able to be split up now but there's no
> guarantee that features we want to add in the future won't introduce
> circular dependencies and other issues.
I find it difficult to reason on hypotheticals.
From a developer's POV, circular dependencies are best avoided.
> Second, having a single module for the current functionality will be
> much more convenient for users. They would just need to pull in a
> single dependency to have access to core functionality for all
> standard dimensions. Plus, a single module makes it much easier to
> discover the overall functionality of the project. This is actually
> how I found out that commons-math had a BSP tree implementation: by
> browsing the code from the source jar. Otherwise, I would have had no
> idea.
I've a bad experience here with "more convenient for users"
arguments: "Commons Math" has remained monolithic primarily
because of it, pulling back development in some packages
because others needed (for some users) to maintain
compatibility with older JVMs.
> Another practical point in my particular case is that I work on a
> project where every 3rd-party artifact needs to be documented and
> approved. Having a bunch of small artifacts makes this really
> difficult.
But this is were Java is going (cf. modularization of the JDK
itself in Java 9)!
Moreover, in the context of Apache and Commons, either one
or more artefacts/modules, the notion of "official release"
is the same and concerns the *source*.
If the issue is with one vs several JAR files, it is readily
solved by creating a so-called "uber" JAR. For user's
convenience, "Commons Geometry" may provide the necessary
maven goal.
> In short, I think modules are great but not at this point for this
> project. I'm picturing all of the existing geometry code as core
> functionality that should be bundled together. As we add more
> features, we can then make decisions about splitting off separate
> modules. It's too early now.
My opinion is that it is never too early to think about
developer's convenience; without developers, no code,
and no users. ;-)
Opposite to the path which you outline, I'd suggest
"make modules", and "merge them" when future needs
demonstrate that it will improve the design.
That being said, I'm just stating what didn't work
out (IMHO) for "Commons Math". But you are going to be
the main driver for development; being the "developer",
your opinion should count more if my arguments do not
convince you.
Could you please forward this thread to the "dev" ML;
it is important to let others chime in (or to just
leave a trace of such discussions)?
Thanks again for your involvement,
Gilles
> Thanks,
> Matt
> ________________________________
> From: Gilles <gil...@harfang.homelinux.org>
> Sent: Saturday, April 7, 2018 5:21 AM
> To: Matt Juntunen
> Subject: Re: Commons Geometry Project Structure
>
> Hello.
>
> On Sat, 7 Apr 2018 01:21:29 +0000, Matt Juntunen wrote:
>> Hi Gillles,
>>
>> I hope I'm not breaking protocol emailing you directly but this is a
>> quick comment and it didn't seem appropriate for the entire dev
>> mailing list. Let me know if this isn't the correct way to handle
>> this. Anyway, I was just going to start on commons-geometry and I
>> noticed that you had just created a multi-module project structure
>> for
>> it. However, I was picturing a single artifact for all of the
>> geometry
>> code since it's all so closely related. It would also make things
>> easier for downstream users since they would only need to pull in a
>> single dependency. What do you think?
>
> No problem in discussing about it on "dev". :-)
> For creating modules, my basic tenet is that the more the better,
> as it helps thinking about real/conceptual dependencies and makes
> the design clearer; e.g.
> * code is "o.a.c.math4.geometry.partitioning" does not depend
> on anything in other subpackages of "o.a.c.math4.geometry"
> * "o.a.c.math4.geometry.euclidean.oned" does not depend on
> other subpackages except "partitioning"
> * ...
>
> One purpose is to make some mathematical relationships obvious
> in delineating the respective modules, defining scopes,
> refactoring, etc.
>
> Downstream users shouldn't have any problem writing (once) a
> stanza for each of the explicit dependencies which they use in
> their code (what they don't use explicitly will be pulled
> automatically by any modern development tool).
>
> Do you foresee specific problems with that approach?
>
> Best regards,
> Gilles
>
>>
>> Thanks,
>> Matt Juntunen
