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

Re: [geometry] Initial Project Structure

Hi Gilles,

That's actually really close to what I ended up with after I started moving the code over. I currently have

  *   commons-geometry-core
  *   commons-geometry-euclidean
  *   commons-geometry-spherical
  *   commons-geometry-hull
  *   commons-geometry-enclosing

So, it's basically split up by space and algorithm. I have the code at https://github.com/darkma773r/commons-geometry/tree/geometry-1. It's not quite ready for a pull request yet but I'm ready for any feedback you or anyone else may have.


From: Gilles <gilles@xxxxxxxxxxxxxxxxxxxxx>
Sent: Thursday, April 12, 2018 9:12 AM
To: dev@xxxxxxxxxxxxxxxxxx
Subject: 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
> 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?

Could we have the following modules:

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



> Thanks,
> 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
>> 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 <gilles@xxxxxxxxxxxxxxxxxxxxx>
>> 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

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