commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles <gil...@harfang.homelinux.org>
Subject Re: [geometry] Initial Project Structure
Date Sat, 14 Apr 2018 13:00:37 GMT
Hello.

On Sat, 14 Apr 2018 04:24:35 +0000, Matt Juntunen wrote:
> 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.

+1

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

I had a brief and very partial look; and noticed the following:
  * Exceptions
    Please have a look at how they are defined, instantiated and
    used in the various modules of "Commons Numbers" (executive
    summary: only JDK exception types are part of the public API)
  * Packages vs (JPMS) modules
    I'd avoid defining classes in "o.a.c.geometry" unless you are
    sure that no other (maven) module than "core" will.
    [Safer would be to create a "o.a.c.geometry.core" package and
     move the "Geometry", "Space", "Point" and "Vector" classes
     into it.]

Regards,
Gilles

>
> -Matt
>
> ________________________________
> From: Gilles <gilles@harfang.homelinux.org>
> Sent: Thursday, April 12, 2018 9:12 AM
> To: dev@commons.apache.org
> 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
>
> ?
>
> Gilles
>
>> Thanks,
>> Matt Juntunen
>>
>>
>> ________________________________________
>> From: Gilles <gilles@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 <gilles@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


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


Mime
View raw message