[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [geometry] Initial Project Structure

Hi Matt.

On Sun, 8 Apr 2018 02:40:26 +0000, Matt Juntunen wrote:
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

  *   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.


Could we have the following modules:

 * commons-geometry-core
 * commons-geometry-euclidean
 * commons-geometry-spherical



Matt Juntunen

From: Gilles <gilles@xxxxxxxxxxxxxxxxxxxxx>
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
will inhibit development. For example, each time we add a new
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

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
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

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

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,

From: Gilles <gilles@xxxxxxxxxxxxxxxxxxxxx>
Sent: Saturday, April 7, 2018 5:21 AM
To: Matt Juntunen
Subject: Re: Commons Geometry Project Structure


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
it. However, I was picturing a single artifact for all of the
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,

Matt Juntunen

To unsubscribe, e-mail: dev-unsubscribe@xxxxxxxxxxxxxxxxxx
For additional commands, e-mail: dev-help@xxxxxxxxxxxxxxxxxx